EW-694 Common Cartridge Course Import

apps/server/src/modules/common-cartridge/import/common-cartridge-file-parser.spec.ts

@@ -0,0 +1,61 @@
+import AdmZip from 'adm-zip';
+import { CommonCartridgeFileParser } from './common-cartridge-file-parser';
+
+describe('CommonCartridgeFileParser', () => {
+	describe('constructor', () => {
+		describe('when manifest file is found', () => {
+			const setup = (manifestName: string) => {
+				const archive = new AdmZip();
+
+				archive.addFile(manifestName, Buffer.from('<manifest></manifest>'));
+
+				const file = archive.toBuffer();
+
+				return { file };
+			};
+
+			it('should use imsmanfiest.xml as manifest', () => {
+				const { file } = setup('imsmanifest.xml');
+				const parser = new CommonCartridgeFileParser(file);
+
+				expect(parser.manifest).toBeDefined();
+			});
+
+			it('should use manfiest.xml as manifest', () => {
+				const { file } = setup('manifest.xml');
+				const parser = new CommonCartridgeFileParser(file);
+
+				expect(parser.manifest).toBeDefined();
+			});
+		});
+
+		describe('when manifest file is not found', () => {
+			const setup = () => {
+				const archive = new AdmZip();
+				const file = archive.toBuffer();
+
+				return { file };
+			};
+
+			it('should throw', () => {
+				const { file } = setup();
+
+				expect(() => new CommonCartridgeFileParser(file)).toThrow('Manifest file not found');
+			});
+		});
+
+		describe('when file is not an archive', () => {
+			const setup = () => {
+				const file = new AdmZip().toBuffer();
+
+				return { file };
+			};
+
+			it('should throw', () => {
+				const { file } = setup();
+
+				expect(() => new CommonCartridgeFileParser(file)).toThrow('Manifest file not found');
+			});
+		});
+	});
+});

apps/server/src/modules/common-cartridge/import/common-cartridge-file-parser.ts

@@ -0,0 +1,22 @@
+import AdmZip from 'adm-zip';
+import { CommonCartridgeManifestParser } from './common-cartridge-manifest-parser';
+
+export class CommonCartridgeFileParser {
+	public readonly manifest: CommonCartridgeManifestParser;
+
+	public constructor(file: Buffer) {
+		const archive = new AdmZip(file);
+
+		this.manifest = new CommonCartridgeManifestParser(this.getManifestFileAsString(archive));
+	}
+
+	private getManifestFileAsString(archive: AdmZip): string | never {
+		const manifest = archive.getEntry('imsmanifest.xml') ?? archive.getEntry('manifest.xml');
+
+		if (manifest) {
+			return archive.readAsText(manifest);
+		}
+
+		throw new Error('Manifest file not found');
+	}
+}

apps/server/src/modules/common-cartridge/import/common-cartridge-manifest-parser.spec.ts

@@ -0,0 +1,46 @@
+import AdmZip from 'adm-zip';
+import { readFile } from 'fs/promises';
+import { CommonCartridgeManifestParser } from './common-cartridge-manifest-parser';
+
+describe('CommonCartridgeManifestParser', () => {
+	const setup = async () => {
+		const buffer = await readFile('./apps/server/test/assets/common-cartridge/us_history_since_1877.imscc');
+		const archive = new AdmZip(buffer);
+		const sut = new CommonCartridgeManifestParser(archive.readAsText('imsmanifest.xml'));
+
+		return { sut };
+	};
+
+	describe('getSchema', () => {
+		describe('when schema is present', () => {
+			it('should return the schema', async () => {
+				const { sut } = await setup();
+				const result = sut.getSchema();
+
+				expect(result).toBe('IMS Common Cartridge');
+			});
+		});
+	});
+
+	describe('getVersion', () => {
+		describe('when version is present', () => {
+			it('should return the version', async () => {
+				const { sut } = await setup();
+				const result = sut.getVersion();
+
+				expect(result).toBe('1.3.0');
+			});
+		});
+	});
+
+	describe('getTitle', () => {
+		describe('when title is present', () => {
+			it('should return the title', async () => {
+				const { sut } = await setup();
+				const result = sut.getTitle();
+
+				expect(result).toBe('201510-AMH-2020-70C-12218-US History Since 1877');
+			});
+		});
+	});
+});

apps/server/src/modules/common-cartridge/import/common-cartridge-manifest-parser.ts

@@ -0,0 +1,27 @@
+import { JSDOM } from 'jsdom';
+
+export class CommonCartridgeManifestParser {
+	private readonly doc: Document;
+
+	public constructor(manifest: string) {
+		this.doc = new JSDOM(manifest).window.document;
+	}
+
+	public getSchema(): string | undefined {
+		const schema = this.doc.querySelector('manifest > metadata > schema');
+
+		return schema?.textContent || undefined;
+	}
+
+	public getVersion(): string | undefined {
+		const version = this.doc.querySelector('manifest > metadata > schemaversion');
+
+		return version?.textContent || undefined;
+	}
+
+	public getTitle(): string | undefined {
+		const title = this.doc.querySelector('manifest > metadata > lom > general > title > string');
+
+		return title?.textContent || undefined;
+	}
+}

apps/server/src/modules/common-cartridge/import/index.ts

@@ -0,0 +1 @@
+export * from './common-cartridge-file-parser';

apps/server/src/modules/learnroom/controller/api-test/course.api.spec.ts

@@ -5,6 +5,7 @@ import { INestApplication, StreamableFile } from '@nestjs/common';
 import { Test, TestingModule } from '@nestjs/testing';
 import { Permission } from '@shared/domain/interface';
 import { TestApiClient, UserAndAccountTestFactory, cleanupCollections, courseFactory } from '@shared/testing';
+import { readFile } from 'node:fs/promises';
 
 const createStudent = () => {
 	const { studentUser, studentAccount } = UserAndAccountTestFactory.buildStudent({}, [Permission.COURSE_VIEW]);
@@ -51,6 +52,7 @@ describe('Course Controller (API)', () => {
 
 			return { student, course, teacher };
 		};
+
 		it('should find courses as student', async () => {
 			const { student, course } = setup();
 			await em.persistAndFlush([student.account, student.user, course]);
@@ -65,6 +67,7 @@ describe('Course Controller (API)', () => {
 			expect(data[0].startDate).toBe(course.startDate);
 			expect(data[0].untilDate).toBe(course.untilDate);
 		});
+
 		it('should find courses as teacher', async () => {
 			const { teacher, course } = setup();
 			await em.persistAndFlush([teacher.account, teacher.user, course]);
@@ -96,6 +99,7 @@ describe('Course Controller (API)', () => {
 
 			return { course, teacher, teacherUnkownToCourse, substitutionTeacher, student1 };
 		};
+
 		it('should find course export', async () => {
 			const { teacher, course } = setup();
 			await em.persistAndFlush([teacher.account, teacher.user, course]);
@@ -114,4 +118,24 @@ describe('Course Controller (API)', () => {
 			expect(response.header['content-disposition']).toBe('attachment;');
 		});
 	});
+
+	describe('[POST] /courses/import', () => {
+		const setup = async () => {
+			const teacher = createTeacher();
+			const course = await readFile('./apps/server/test/assets/common-cartridge/us_history_since_1877.imscc');
+
+			return { teacher, course };
+		};
+
+		it('should import course', async () => {
+			const { teacher, course } = await setup();
+			await em.persistAndFlush([teacher.account, teacher.user]);
+			em.clear();
+
+			const loggedInClient = await testApiClient.login(teacher.account);
+			const response = await loggedInClient.postWithAttachment('import', 'file', course, 'us_history_since_1877.imscc');
+
+			expect(response.statusCode).toEqual(201);
+		});
+	});
 });

apps/server/src/modules/learnroom/controller/course.controller.ts

@@ -1,13 +1,39 @@
 import { Authenticate, CurrentUser, ICurrentUser } from '@modules/authentication';
-import { Controller, Get, NotFoundException, Param, Query, Res, StreamableFile } from '@nestjs/common';
+import {
+	Controller,
+	FileTypeValidator,
+	Get,
+	MaxFileSizeValidator,
+	NotFoundException,
+	Param,
+	ParseFilePipe,
+	Post,
+	Query,
+	Res,
+	StreamableFile,
+	UploadedFile,
+	UseInterceptors,
+} from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
-import { ApiTags } from '@nestjs/swagger';
+import { FileInterceptor } from '@nestjs/platform-express';
+import {
+	ApiBadRequestResponse,
+	ApiBody,
+	ApiConsumes,
+	ApiCreatedResponse,
+	ApiInternalServerErrorResponse,
+	ApiOperation,
+	ApiTags,
+} from '@nestjs/swagger';
 import { PaginationParams } from '@shared/controller/';
+import { config } from '@src/modules/files-storage/files-storage.config';
 import { Response } from 'express';
 import { CourseMapper } from '../mapper/course.mapper';
+import { CourseImportUc } from '../uc';
 import { CourseExportUc } from '../uc/course-export.uc';
 import { CourseUc } from '../uc/course.uc';
-import { CourseMetadataListResponse, CourseQueryParams, CourseUrlParams } from './dto';
+import { CommonCartridgeFileValidator } from '../utils';
+import { CourseImportBodyParams, CourseMetadataListResponse, CourseQueryParams, CourseUrlParams } from './dto';
 
 @ApiTags('Courses')
 @Authenticate('jwt')
@@ -16,6 +42,7 @@ export class CourseController {
 	constructor(
 		private readonly courseUc: CourseUc,
 		private readonly courseExportUc: CourseExportUc,
+		private readonly courseImportUc: CourseImportUc,
 		private readonly configService: ConfigService
 	) {}
 
@@ -47,4 +74,28 @@ export class CourseController {
 		});
 		return new StreamableFile(result);
 	}
+
+	@Post('import')
+	@UseInterceptors(FileInterceptor('file'))
+	@ApiOperation({ summary: 'Imports a course from a Common Cartridge file.' })
+	@ApiConsumes('multipart/form-data')
+	@ApiBody({ type: CourseImportBodyParams, required: true })
+	@ApiCreatedResponse({ description: 'Course was successfully imported.' })
+	@ApiBadRequestResponse({ description: 'Request data has invalid format.' })
+	@ApiInternalServerErrorResponse({ description: 'Internal server error.' })
+	public async importCourse(
+		@CurrentUser() currentUser: ICurrentUser,
+		@UploadedFile(
+			new ParseFilePipe({
+				validators: [
+					new MaxFileSizeValidator({ maxSize: config().MAX_FILE_SIZE }),
+					new FileTypeValidator({ fileType: /application\/(octet-stream|.*zip.*)/ }),
+					new CommonCartridgeFileValidator(),
+				],
+			})
+		)
+		file: Express.Multer.File
+	): Promise<void> {
+		await this.courseImportUc.importFromCommonCartridge(currentUser.userId, file.buffer);
+	}
 }

apps/server/src/modules/learnroom/controller/dto/course-import.body.params.ts

@@ -0,0 +1,11 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CourseImportBodyParams {
+	@ApiProperty({
+		type: String,
+		format: 'binary',
+		required: true,
+		description: 'The Common Cartridge file to import.',
+	})
+	file!: Express.Multer.File;
+}

apps/server/src/modules/learnroom/controller/dto/index.ts

@@ -1,5 +1,7 @@
-export * from './course.url.params';
+export * from './course-import.body.params';
 export * from './course-metadata.response';
+export * from './course.query.params';
+export * from './course.url.params';
 export * from './dashboard.response';
 export * from './dashboard.url.params';
 export * from './lesson';
@@ -10,4 +12,3 @@ export * from './patch-visibility.params';
 export * from './room-element.url.params';
 export * from './room.url.params';
 export * from './single-column-board';
-export * from './course.query.params';

apps/server/src/modules/learnroom/index.ts

@@ -1,9 +1,10 @@
+export * from './learnroom.config';
 export * from './learnroom.module';
 export {
 	CommonCartridgeExportService,
 	CourseCopyService,
-	CourseService,
-	RoomsService,
 	CourseGroupService,
+	CourseService,
 	DashboardService,
+	RoomsService,
 } from './service';

apps/server/src/modules/learnroom/learnroom-api.module.ts

@@ -12,6 +12,7 @@ import { RoomBoardResponseMapper } from './mapper/room-board-response.mapper';
 import {
 	CourseCopyUC,
 	CourseExportUc,
+	CourseImportUc,
 	CourseUc,
 	DashboardUc,
 	LessonCopyUC,
@@ -33,6 +34,7 @@ import {
 		CourseCopyUC,
 		RoomsAuthorisationService,
 		CourseExportUc,
+		CourseImportUc,
 		// FIXME Refactor UCs to use services and remove these imports
 		{
 			provide: 'DASHBOARD_REPO',

apps/server/src/modules/learnroom/learnroom.config.ts

@@ -0,0 +1,3 @@
+export interface LearnroomConfig {
+	FEATURE_COMMON_CARTRIDGE_COURSE_IMPORT_ENABLED: boolean;
+}

apps/server/src/modules/learnroom/learnroom.module.ts

@@ -18,6 +18,7 @@ import {
 	BoardCopyService,
 	ColumnBoardTargetService,
 	CommonCartridgeExportService,
+	CommonCartridgeImportService,
 	CourseCopyService,
 	CourseGroupService,
 	CourseService,
@@ -51,6 +52,7 @@ import { ToolConfigModule } from '../tool/tool-config.module';
 		RoomsService,
 		CourseService,
 		CommonCartridgeExportService,
+		CommonCartridgeImportService,
 		ColumnBoardTargetService,
 		CourseGroupService,
 		CourseGroupRepo,
@@ -61,6 +63,7 @@ import { ToolConfigModule } from '../tool/tool-config.module';
 		CourseService,
 		RoomsService,
 		CommonCartridgeExportService,
+		CommonCartridgeImportService,
 		CourseGroupService,
 		DashboardService,
 	],