@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/media/services/s3.service.ts

@@ -0,0 +1,168 @@
+import {
+	BadRequestException,
+	Injectable,
+	ServiceUnavailableException
+} from '@nestjs/common';
+import {
+	S3Client,
+	PutObjectCommand,
+	DeleteObjectCommand,
+	GetObjectCommand
+} from '@aws-sdk/client-s3';
+import path from 'path';
+import {
+	CustomConfigService,
+	GeneratorService,
+	LoggerService
+} from 'common/services';
+import { Enum } from 'common/utils';
+
+@Injectable()
+export class S3Service {
+	private client: S3Client;
+
+	constructor(
+		private config: CustomConfigService,
+		private gen: GeneratorService,
+		private logger: LoggerService
+	) {
+		const { accessKeyId, region, endpoint, secretAccessKey } = this.config.s3;
+		this.client = new S3Client({
+			region,
+			endpoint,
+			credentials: {
+				accessKeyId,
+				secretAccessKey
+			},
+			forcePathStyle: true,
+			// Without these the SDK defaults leave a request outstanding for minutes
+			// when the storage host accepts the TCP connection but never answers —
+			// every caller (statement import, avatars, feedback attachments) inherits
+			// that hang. Bound it so an unreachable bucket surfaces as a fast error.
+			requestHandler: {
+				connectionTimeout: 5_000,
+				// Socket-inactivity timeout, so a steadily streaming large upload will
+				// not trip it. Sized with `maxAttempts` so the worst case (~30s) lands
+				// inside the client's own upload timeout — the browser must receive our
+				// error rather than give up first and show a generic "connection lost".
+				requestTimeout: 15_000,
+				// Without this the handler only logs a warning when requestTimeout
+				// elapses and lets the socket keep hanging — the timeout has to be
+				// opted into as an actual error.
+				throwOnRequestTimeout: true
+			},
+			maxAttempts: 2
+		});
+	}
+
+	private get pathPrefix() {
+		const { endpoint, bucket } = this.config.s3;
+		return `${endpoint}/${bucket}/`;
+	}
+
+	getKey(
+		folder: Enum.UploadFolder,
+		file: Express.Multer.File,
+		name?: string
+	): string {
+		return `${folder}/${name ?? this.gen.cuid()}${path.extname(
+			file.originalname
+		)}`;
+	}
+
+	getKeyFromUrl(url: string) {
+		return url.replace(this.pathPrefix, '');
+	}
+
+	getUrl(key: string) {
+		return this.pathPrefix + key;
+	}
+
+	isHostedUrl(url: string) {
+		return url.startsWith(this.pathPrefix);
+	}
+
+	/**
+	 * Storage failures are not the caller's fault. A timeout / DNS / refused-connection
+	 * error means the bucket host is unreachable — that is a 503 the client can retry,
+	 * not a 400 telling the user their file was bad. Anything else (missing key, bad
+	 * ACL) stays a 400 as before.
+	 */
+	private toException(error: any, action: 'store' | 'read') {
+		const transportCodes = [
+			'TimeoutError',
+			'ECONNREFUSED',
+			'ECONNRESET',
+			'ENOTFOUND',
+			'EAI_AGAIN',
+			'EPIPE',
+			'ETIMEDOUT'
+		];
+		const code = error?.name ?? error?.code;
+		const unreachable =
+			transportCodes.includes(code) ||
+			transportCodes.includes(error?.$metadata?.httpStatusCode) ||
+			error?.$metadata?.httpStatusCode >= 500;
+
+		if (unreachable) {
+			this.logger.error(
+				{ err: error, action, endpoint: this.config.s3.endpoint },
+				'File storage is unreachable.'
+			);
+			return new ServiceUnavailableException(
+				`We could not ${action} the file right now — storage is unavailable. Please try again shortly.`
+			);
+		}
+		return new BadRequestException(error.message);
+	}
+
+	async uploadFile(file: Express.Multer.File, folder: Enum.UploadFolder) {
+		try {
+			const key = this.getKey(folder, file);
+			const acl = Enum.isPrivateUploadFolder(folder)
+				? 'private'
+				: 'public-read';
+			const command = new PutObjectCommand({
+				Bucket: this.config.s3.bucket,
+				Key: key,
+				Body: file.buffer,
+				ContentType: file.mimetype,
+				ACL: acl,
+				Metadata: {
+					originalName: file.originalname
+				}
+			});
+			await this.client.send(command);
+			return this.getUrl(key);
+		} catch (error: any) {
+			throw this.toException(error, 'store');
+		}
+	}
+
+	async getFileBuffer(key: string): Promise<Buffer> {
+		try {
+			const command = new GetObjectCommand({
+				Bucket: this.config.s3.bucket,
+				Key: key
+			});
+			const response = await this.client.send(command);
+			const bytes = await response.Body!.transformToByteArray();
+			return Buffer.from(bytes);
+		} catch (error: any) {
+			throw this.toException(error, 'read');
+		}
+	}
+
+	async deleteFile(key: string) {
+		try {
+			const command = new DeleteObjectCommand({
+				Bucket: this.config.s3.bucket,
+				Key: key
+			});
+
+			await this.client.send(command);
+		} catch (error: any) {
+			throw new BadRequestException(error.message);
+		}
+	}
+}

package/templates/nest-api/files/src/notifications/controllers/index.ts

@@ -0,0 +1 @@
+export * from './notifications.controller';

package/templates/nest-api/files/src/notifications/controllers/notifications.controller.ts

@@ -0,0 +1,72 @@
+import {
+	Controller,
+	Get,
+	HttpCode,
+	Param,
+	Patch,
+	Post,
+	Query
+} from '@nestjs/common';
+import { ApiNotFoundResponse, ApiTags } from '@nestjs/swagger';
+import { Session, UserSession } from '@thallesp/nestjs-better-auth';
+import { IdParam, Op, Returns } from 'common/decorators';
+import { OKEntity } from 'common/entity';
+import { NotificationsService } from '../services';
+import {
+	NotificationEntity,
+	PaginatedNotificationEntity,
+	UnreadCountEntity
+} from '../entity';
+import { NotificationFilters } from '../dto';
+
+@ApiTags('Notifications')
+@Controller({ path: 'notifications', version: '1' })
+export class NotificationsController {
+	constructor(private readonly notifications: NotificationsService) {}
+
+	@Get()
+	@Op('listNotifications', '/v1/notifications', 'List your notifications')
+	@Returns(PaginatedNotificationEntity)
+	list(
+		@Session() { user }: UserSession,
+		@Query({ schema: NotificationFilters }) filters: NotificationFilters
+	) {
+		return this.notifications.list(user.id, filters);
+	}
+
+	@Get('unread-count')
+	@Op(
+		'getUnreadNotificationCount',
+		'/v1/notifications/unread-count',
+		'Count your unread notifications'
+	)
+	@Returns(UnreadCountEntity)
+	unreadCount(@Session() { user }: UserSession) {
+		return this.notifications.unreadCount(user.id);
+	}
+
+	@Patch(':id/read')
+	@Op(
+		'markNotificationRead',
+		'/v1/notifications/:id/read',
+		'Mark a single notification as read'
+	)
+	@IdParam()
+	@Returns(NotificationEntity)
+	@ApiNotFoundResponse({ description: 'Notification not found' })
+	markRead(@Session() { user }: UserSession, @Param('id') id: string) {
+		return this.notifications.markRead(user.id, id);
+	}
+
+	@Post('read-all')
+	@Op(
+		'markAllNotificationsRead',
+		'/v1/notifications/read-all',
+		'Mark all your notifications as read'
+	)
+	@HttpCode(200)
+	@Returns(OKEntity)
+	markAllRead(@Session() { user }: UserSession) {
+		return this.notifications.markAllRead(user.id);
+	}
+}

package/templates/nest-api/files/src/notifications/dto/index.ts

@@ -0,0 +1 @@
+export * from './notification.dto';

package/templates/nest-api/files/src/notifications/dto/notification.dto.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { CommonFilters } from 'common/dto';
+
+export const NotificationFilters = CommonFilters.extend({
+	// "true"/"1"/"yes"/"on" and their opposites; anything else is rejected.
+	unread: z
+		.stringbool()
+		.optional()
+		.meta({ description: 'Return only unread notifications', example: true })
+});
+export type NotificationFilters = z.output<typeof NotificationFilters>;

package/templates/nest-api/files/src/notifications/entity/index.ts

@@ -0,0 +1 @@
+export * from './notification.entity';

package/templates/nest-api/files/src/notifications/entity/notification.entity.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { NotificationType } from '@db/client';
+import { dateTime } from 'common/schemas';
+import { paginated } from 'common/entity';
+
+export const NotificationEntity = z
+	.object({
+		id: z.string(),
+		userId: z.string(),
+		type: z.enum(NotificationType).meta({ example: 'reply' }),
+		// Free-form JSON, as stored; typed to accept Prisma's JsonValue.
+		data: z.unknown().meta({
+			type: 'object',
+			description:
+				'Type-specific payload for deep-linking, e.g. { postId, commentId, target }',
+			example: { postId: 'ckp...', commentId: 'ckq...' }
+		}),
+		readAt: dateTime().nullable(),
+		createdAt: dateTime()
+	})
+	.meta({ id: 'NotificationEntity' });
+/** What a service hands back; the schema turns it into the response. */
+export type NotificationEntity = z.input<typeof NotificationEntity>;
+
+export const PaginatedNotificationEntity = paginated(
+	NotificationEntity,
+	'PaginatedNotificationEntity'
+);
+export type PaginatedNotificationEntity = z.input<
+	typeof PaginatedNotificationEntity
+>;
+
+/** Lightweight badge payload for the unread counter. */
+export const UnreadCountEntity = z
+	.object({ count: z.number().meta({ example: 3 }) })
+	.meta({ id: 'UnreadCountEntity' });
+export type UnreadCountEntity = z.input<typeof UnreadCountEntity>;

package/templates/nest-api/files/src/notifications/notifications.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { NotificationsController } from './controllers';
+import { NotificationsService } from './services';
+
+@Module({
+	controllers: [NotificationsController],
+	providers: [NotificationsService],
+	// Exported so any producing module can dispatch notifications.
+	exports: [NotificationsService]
+})
+export class NotificationsModule {}

package/templates/nest-api/files/src/notifications/services/index.ts

@@ -0,0 +1 @@
+export * from './notifications.service';

package/templates/nest-api/files/src/notifications/services/notifications.service.ts

@@ -0,0 +1,98 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { NotificationType, Prisma } from '@db/client';
+import { PrismaService, LoggerService } from 'common/services';
+import { ok } from 'common/entity';
+import { RealtimeService } from 'realtime/services/realtime.service';
+import {
+	NotificationEntity,
+	PaginatedNotificationEntity,
+	UnreadCountEntity
+} from '../entity';
+import { NotificationFilters } from '../dto';
+
+@Injectable()
+export class NotificationsService {
+	constructor(
+		private readonly db: PrismaService,
+		private readonly realtime: RealtimeService,
+		private readonly logger: LoggerService
+	) {}
+
+	/**
+	 * Persist a notification, then push it to the recipient's live sockets.
+	 *
+	 * This is the write side other modules call: storing first
+	 * means the alert survives an offline recipient — the socket emit is just the
+	 * real-time bonus for anyone currently connected. Never throws: a notification
+	 * failing must not fail the action that triggered it (a comment, a vote), so
+	 * errors are swallowed and logged, mirroring `RealtimeService`'s emit policy.
+	 */
+	async dispatch(
+		userId: string,
+		type: NotificationType,
+		data: Prisma.InputJsonValue
+	): Promise<NotificationEntity | null> {
+		try {
+			const notification = await this.db.notification.create({
+				data: { userId, type, data }
+			});
+			// Sockets bypass the HTTP serializer; encode through the same schema so
+			// the event has exactly the shape the REST endpoints return.
+			this.realtime.notifyUser(userId, NotificationEntity.parse(notification));
+			return notification;
+		} catch (err) {
+			this.logger.warn(
+				{ err, userId, type },
+				'Failed to dispatch notification.'
+			);
+			return null;
+		}
+	}
+
+	async list(
+		userId: string,
+		filters: NotificationFilters
+	): Promise<PaginatedNotificationEntity> {
+		const where: Prisma.NotificationWhereInput = { userId };
+		if (filters.unread) where.readAt = null;
+
+		const [list, meta] = await this.db.x.notification.paginate({
+			where,
+			page: filters.page,
+			limit: filters.limit,
+			orderBy: { createdAt: 'desc' }
+		});
+
+		return { list, ...meta };
+	}
+
+	async unreadCount(userId: string): Promise<UnreadCountEntity> {
+		const count = await this.db.notification.count({
+			where: { userId, readAt: null }
+		});
+		return { count };
+	}
+
+	async markRead(userId: string, id: string): Promise<NotificationEntity> {
+		const existing = await this.db.notification.findFirst({
+			where: { id, userId }
+		});
+		if (!existing) throw new NotFoundException('Notification not found');
+
+		// Idempotent: re-reading an already-read notification is a no-op.
+		if (existing.readAt) return existing;
+
+		return this.db.notification.update({
+			where: { id },
+			data: { readAt: new Date() }
+		});
+	}
+
+	async markAllRead(userId: string) {
+		await this.db.notification.updateMany({
+			where: { userId, readAt: null },
+			data: { readAt: new Date() }
+		});
+		return ok();
+	}
+}

package/templates/nest-api/files/src/realtime/__tests__/events.gateway.spec.ts

@@ -0,0 +1,88 @@
+import { WsException } from '@nestjs/websockets';
+import { Socket } from 'socket.io';
+import { EventsGateway } from '../gateways/events.gateway';
+import { FEED_ROOM, channelRoom, userRoom } from '../constants';
+
+const makeSocket = (rooms: string[] = []) =>
+	({
+		id: 'socket-1',
+		data: {
+			user: { id: 'me', name: 'Me', email: 'me@test.com', role: 'user' }
+		},
+		rooms: new Set(['socket-1', ...rooms]),
+		join: vi.fn().mockResolvedValue(undefined),
+		leave: vi.fn().mockResolvedValue(undefined),
+		to: vi.fn().mockReturnValue({ emit: vi.fn() })
+	}) as unknown as Socket;
+
+const makeGateway = () =>
+	new EventsGateway(
+		{} as never,
+		{ online: vi.fn() } as never,
+		{ bindServer: vi.fn() } as never,
+		{ debug: vi.fn() } as never
+	);
+
+describe('EventsGateway', () => {
+	describe('joinRoom', () => {
+		it('joins an allowed channel room', async () => {
+			const gateway = makeGateway();
+			const socket = makeSocket();
+
+			await expect(
+				gateway.joinRoom(socket, { room: channelRoom('clx1') })
+			).resolves.toEqual({ ok: true, room: channelRoom('clx1') });
+			expect(socket.join).toHaveBeenCalledWith(channelRoom('clx1'));
+		});
+
+		it("refuses to join another user's notification room", async () => {
+			const gateway = makeGateway();
+			const socket = makeSocket();
+
+			await expect(
+				gateway.joinRoom(socket, { room: userRoom('victim') })
+			).rejects.toThrow(WsException);
+			expect(socket.join).not.toHaveBeenCalled();
+		});
+
+		it('refuses to join a room that is not on the allowlist', async () => {
+			const gateway = makeGateway();
+			const socket = makeSocket();
+
+			await expect(
+				gateway.joinRoom(socket, { room: 'admin:secrets' })
+			).rejects.toThrow(WsException);
+			expect(socket.join).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('typing / viewing', () => {
+		it('relays into a room the socket occupies', () => {
+			const gateway = makeGateway();
+			const socket = makeSocket([FEED_ROOM]);
+
+			gateway.typing(socket, { room: FEED_ROOM, isTyping: true });
+			expect(socket.to).toHaveBeenCalledWith(FEED_ROOM);
+		});
+
+		it('refuses to forge a typing signal into a room it never joined', () => {
+			const gateway = makeGateway();
+			const socket = makeSocket();
+
+			expect(() =>
+				gateway.typing(socket, { room: userRoom('victim'), isTyping: true })
+			).toThrow(WsException);
+			expect(socket.to).not.toHaveBeenCalled();
+		});
+
+		it('refuses to forge a viewing signal into a room it never joined', () => {
+			const gateway = makeGateway();
+			const socket = makeSocket();
+
+			expect(() =>
+				gateway.viewing(socket, { room: channelRoom('clx1'), viewing: true })
+			).toThrow(WsException);
+			expect(socket.to).not.toHaveBeenCalled();
+		});
+	});
+});

package/templates/nest-api/files/src/realtime/__tests__/rooms.spec.ts

@@ -0,0 +1,29 @@
+import { FEED_ROOM, isJoinableRoom, channelRoom, userRoom } from '../constants';
+
+describe('isJoinableRoom', () => {
+	it('allows the feed and individual channel rooms', () => {
+		expect(isJoinableRoom(FEED_ROOM)).toBe(true);
+		expect(isJoinableRoom(channelRoom('clx123abc'))).toBe(true);
+	});
+
+	// The bug this closes: `room:join` used to call socket.join(body.room) with
+	// whatever string arrived, so any authenticated user could join another
+	// user's notification room and read their private notifications.
+	it("refuses another user's private notification room", () => {
+		expect(isJoinableRoom(userRoom('some-other-user-id'))).toBe(false);
+		expect(isJoinableRoom('user:')).toBe(false);
+	});
+
+	it('refuses arbitrary and malformed room names', () => {
+		expect(isJoinableRoom('')).toBe(false);
+		expect(isJoinableRoom('feed:extra')).toBe(false);
+		expect(isJoinableRoom('channel:')).toBe(false);
+		expect(isJoinableRoom('channel:abc:def')).toBe(false);
+		expect(isJoinableRoom('anything-at-all')).toBe(false);
+	});
+
+	it('is not fooled by a prefix that merely starts with a joinable room', () => {
+		expect(isJoinableRoom('feedxyz')).toBe(false);
+		expect(isJoinableRoom('xchannel:abc')).toBe(false);
+	});
+});

package/templates/nest-api/files/src/realtime/__tests__/ws-permissions.guard.spec.ts

@@ -0,0 +1,54 @@
+import { ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { WsException } from '@nestjs/websockets';
+import { WsPermissionsGuard } from '../guards';
+import { SocketUser } from '../misc/session-from-socket';
+
+const contextFor = (user?: Partial<SocketUser>) =>
+	({
+		getHandler: () => vi.fn(),
+		getClass: () => vi.fn(),
+		switchToWs: () => ({
+			getClient: () => ({ data: user ? { user } : {} })
+		})
+	}) as unknown as ExecutionContext;
+
+const guardWith = (required: unknown) => {
+	const reflector = {
+		getAllAndOverride: vi.fn().mockReturnValue(required)
+	} as unknown as Reflector;
+	return new WsPermissionsGuard(reflector);
+};
+
+describe('WsPermissionsGuard', () => {
+	it('allows a handler that declares no permission', () => {
+		const guard = guardWith(undefined);
+		expect(guard.canActivate(contextFor({ role: 'user' }))).toBe(true);
+	});
+
+	it('allows a role that holds the required permission', () => {
+		const guard = guardWith({ session: ['list'] });
+		expect(guard.canActivate(contextFor({ role: 'user' }))).toBe(true);
+	});
+
+	it('rejects a role that lacks the required permission', () => {
+		const guard = guardWith({ user: ['ban'] });
+		expect(() => guard.canActivate(contextFor({ role: 'user' }))).toThrow(
+			WsException
+		);
+	});
+
+	it('rejects an unauthenticated socket even when a permission is declared', () => {
+		const guard = guardWith({ session: ['list'] });
+		expect(() => guard.canActivate(contextFor())).toThrow(WsException);
+	});
+
+	it('rejects an unauthenticated socket before consulting permissions', () => {
+		const guard = guardWith({ session: ['list'] });
+		try {
+			guard.canActivate(contextFor());
+		} catch (error) {
+			expect((error as WsException).message).toBe('Unauthorized');
+		}
+	});
+});

package/templates/nest-api/files/src/realtime/adapters/redis-io.adapter.ts

@@ -0,0 +1,57 @@
+import { INestApplicationContext } from '@nestjs/common';
+import { IoAdapter } from '@nestjs/platform-socket.io';
+import { ServerOptions } from 'socket.io';
+import { createAdapter } from '@socket.io/redis-adapter';
+import IoRedis from 'ioredis';
+import { CustomConfigService } from 'common/services';
+import { CORS_OPTIONS } from 'common/constants';
+import { SOCKET_PATH } from '../constants';
+
+/**
+ * Socket.io adapter backed by a Redis pub/sub pair.
+ *
+ * Every backend replica publishes emitted events onto Redis and subscribes to
+ * the others, so a `server.to(room).emit(...)` fans out to clients regardless
+ * of which instance holds their socket. This is the "Redis-backed adapter for
+ * horizontal scaling" called for in the PRD (§3.1).
+ *
+ * Wire it in `main.ts` before `app.listen()`:
+ *
+ *   const adapter = new RedisIoAdapter(app);
+ *   await adapter.connectToRedis(app.get(CustomConfigService));
+ *   app.useWebSocketAdapter(adapter);
+ */
+export class RedisIoAdapter extends IoAdapter {
+	private adapterConstructor?: ReturnType<typeof createAdapter>;
+
+	constructor(private readonly app: INestApplicationContext) {
+		super(app);
+	}
+
+	async connectToRedis(config: CustomConfigService): Promise<void> {
+		const pubClient = new IoRedis({ ...config.redis });
+		const subClient = pubClient.duplicate();
+		this.adapterConstructor = createAdapter(pubClient, subClient);
+	}
+
+	createIOServer(port: number, options?: ServerOptions) {
+		// IoAdapter types this as the full ServerOptions; socket.io fills the rest.
+		const server = super.createIOServer(port, {
+			...options,
+			path: SOCKET_PATH,
+			// Reuse the REST CORS allow-list so the browser can open the socket.
+			cors: {
+				origin: CORS_OPTIONS.origin,
+				credentials: true
+			}
+		} as ServerOptions);
+
+		// `connectToRedis` may not have run in envs where scaling is unnecessary
+		// (e.g. tests); fall back to the default in-memory adapter in that case.
+		if (this.adapterConstructor) {
+			server.adapter(this.adapterConstructor);
+		}
+
+		return server;
+	}
+}