create-fullstack-scaffold 0.1.0

package/template/src/server/module-file/__tests__/file-storage-service.test.ts

@@ -0,0 +1,323 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect, afterAll } from 'vitest'
+import {
+  saveFile,
+  readFileData,
+  deleteFile,
+  getFileInfo,
+  fileExists,
+  getFilePath,
+  getPublicFileUrl,
+  getPrivateFileUrl,
+  generateSignature,
+  verifySignature,
+  cleanupTempFiles,
+  getFileStorageConfig,
+  getUploadConfig,
+  validateFile,
+} from '@server/utils/file-storage'
+import { unlink } from 'fs/promises'
+import { existsSync } from 'fs'
+
+describe('File Storage Service', () => {
+  const testNamespace = 'test-storage'
+  let testFilePath: string
+
+  afterAll(async () => {
+    await cleanupTempFiles()
+  })
+
+  describe('saveFile', () => {
+    it('should save file successfully with valid data', async () => {
+      const content = new Uint8Array(Buffer.from('Test file content'))
+      const result = await saveFile(testNamespace, {
+        name: 'test.txt',
+        type: 'text/plain',
+        size: content.length,
+        data: content.buffer as ArrayBuffer,
+      })
+
+      expect(result.filename).toBeDefined()
+      expect(result.originalName).toBe('test.txt')
+      expect(result.mimeType).toBe('text/plain')
+      expect(result.size).toBe(content.length)
+      expect(result.path).toContain(testNamespace)
+      expect(result.extension).toBe('.txt')
+
+      testFilePath = result.path
+
+      // Cleanup
+      await unlink(testFilePath)
+    })
+
+    it('should throw error for file exceeding max size', async () => {
+      const largeContent = new Uint8Array(11 * 1024 * 1024) // 11MB
+      await expect(
+        saveFile(testNamespace, {
+          name: 'large.txt',
+          type: 'text/plain',
+          size: largeContent.length,
+          data: largeContent.buffer as ArrayBuffer,
+        })
+      ).rejects.toThrow('File size exceeds maximum allowed size')
+    })
+
+    it('should throw error for invalid file type', async () => {
+      const content = new Uint8Array(Buffer.from('Test content'))
+      await expect(
+        saveFile(testNamespace, {
+          name: 'test.exe',
+          type: 'application/x-msdownload',
+          size: content.length,
+          data: content.buffer as ArrayBuffer,
+        })
+      ).rejects.toThrow('File type')
+    })
+
+    it('should throw error for invalid file extension', async () => {
+      const content = new Uint8Array(Buffer.from('Test content'))
+      await expect(
+        saveFile(testNamespace, {
+          name: 'test.bat',
+          type: 'text/plain',
+          size: content.length,
+          data: content.buffer as ArrayBuffer,
+        })
+      ).rejects.toThrow('File extension')
+    })
+  })
+
+  describe('readFileData', () => {
+    it('should read file data successfully', async () => {
+      const content = new Uint8Array(Buffer.from('Test content for reading'))
+      const saved = await saveFile(testNamespace, {
+        name: 'readable.txt',
+        type: 'text/plain',
+        size: content.length,
+        data: content.buffer as ArrayBuffer,
+      })
+
+      const data = await readFileData(saved.path)
+      expect(data.toString()).toBe('Test content for reading')
+
+      // Cleanup
+      await unlink(saved.path)
+    })
+
+    it('should throw error for non-existent file', async () => {
+      await expect(readFileData('/non/existent/file.txt')).rejects.toThrow('File not found')
+    })
+  })
+
+  describe('deleteFile', () => {
+    it('should delete file successfully', async () => {
+      const content = new Uint8Array(Buffer.from('Test content'))
+      const saved = await saveFile(testNamespace, {
+        name: 'deletable.txt',
+        type: 'text/plain',
+        size: content.length,
+        data: content.buffer as ArrayBuffer,
+      })
+
+      expect(existsSync(saved.path)).toBe(true)
+
+      const result = await deleteFile(saved.path)
+      expect(result).toBe(true)
+      expect(existsSync(saved.path)).toBe(false)
+    })
+
+    it('should return true for non-existent file', async () => {
+      const result = await deleteFile('/non/existent/file.txt')
+      expect(result).toBe(true)
+    })
+  })
+
+  describe('getFileInfo', () => {
+    it('should return file info for existing file', async () => {
+      const content = new Uint8Array(Buffer.from('Test content'))
+      const saved = await saveFile(testNamespace, {
+        name: 'info.txt',
+        type: 'text/plain',
+        size: content.length,
+        data: content.buffer as ArrayBuffer,
+      })
+
+      const info = await getFileInfo(testNamespace, saved.filename)
+      expect(info).not.toBeNull()
+      expect(info?.size).toBe(content.length)
+      expect(info?.mimeType).toBe('text/plain')
+      expect(info?.lastModified).toBeInstanceOf(Date)
+
+      // Cleanup
+      await unlink(saved.path)
+    })
+
+    it('should return null for non-existent file', async () => {
+      const info = await getFileInfo(testNamespace, 'non-existent.txt')
+      expect(info).toBeNull()
+    })
+  })
+
+  describe('fileExists', () => {
+    it('should return true for existing file', async () => {
+      const content = new Uint8Array(Buffer.from('Test content'))
+      const saved = await saveFile(testNamespace, {
+        name: 'exists.txt',
+        type: 'text/plain',
+        size: content.length,
+        data: content.buffer as ArrayBuffer,
+      })
+
+      const exists = await fileExists(testNamespace, saved.filename)
+      expect(exists).toBe(true)
+
+      // Cleanup
+      await unlink(saved.path)
+    })
+
+    it('should return false for non-existent file', async () => {
+      const exists = await fileExists(testNamespace, 'non-existent.txt')
+      expect(exists).toBe(false)
+    })
+  })
+
+  describe('getFilePath', () => {
+    it('should return correct file path', () => {
+      const path = getFilePath(testNamespace, 'test.txt')
+      expect(path).toContain(testNamespace)
+      expect(path).toContain('test.txt')
+    })
+  })
+
+  describe('getPublicFileUrl', () => {
+    it('should return public URL without baseUrl', () => {
+      const url = getPublicFileUrl(testNamespace, 'test.txt')
+      expect(url).toBe(`/files/public/${testNamespace}/test.txt`)
+    })
+
+    it('should return public URL with baseUrl', () => {
+      const url = getPublicFileUrl(testNamespace, 'test.txt', 'https://example.com')
+      expect(url).toBe(`https://example.com/files/public/${testNamespace}/test.txt`)
+    })
+  })
+
+  describe('getPrivateFileUrl', () => {
+    it('should return private URL with expiry and signature', () => {
+      const { url, expiry } = getPrivateFileUrl(testNamespace, 'test.txt', 3600)
+      expect(url).toContain(`/files/private/${testNamespace}/test.txt`)
+      expect(url).toContain('expiry=')
+      expect(url).toContain('signature=')
+      expect(expiry).toBeGreaterThan(Math.floor(Date.now() / 1000))
+    })
+
+    it('should use default expiry when not specified', () => {
+      const { url, expiry } = getPrivateFileUrl(testNamespace, 'test.txt')
+      expect(url).toContain('expiry=')
+      expect(expiry).toBeGreaterThan(Math.floor(Date.now() / 1000))
+    })
+  })
+
+  describe('generateSignature and verifySignature', () => {
+    it('should generate and verify valid signature', () => {
+      const expiry = Math.floor(Date.now() / 1000) + 3600
+      const signature = generateSignature(testNamespace, 'test.txt', expiry)
+
+      expect(signature).toBeDefined()
+      expect(signature.length).toBeGreaterThan(0)
+
+      const isValid = verifySignature(testNamespace, 'test.txt', expiry, signature)
+      expect(isValid).toBe(true)
+    })
+
+    it('should reject invalid signature', () => {
+      const expiry = Math.floor(Date.now() / 1000) + 3600
+      const isValid = verifySignature(testNamespace, 'test.txt', expiry, 'invalid-signature')
+      expect(isValid).toBe(false)
+    })
+
+    it('should reject signature with different parameters', () => {
+      const expiry = Math.floor(Date.now() / 1000) + 3600
+      const signature = generateSignature(testNamespace, 'test.txt', expiry)
+
+      const isValid = verifySignature(testNamespace, 'other.txt', expiry, signature)
+      expect(isValid).toBe(false)
+    })
+  })
+
+  describe('getFileStorageConfig', () => {
+    it('should return default config', () => {
+      const config = getFileStorageConfig()
+      expect(config.baseDir).toBeDefined()
+      expect(config.tempDir).toBeDefined()
+      expect(config.tempFileTTL).toBeDefined()
+      expect(config.privateUrlExpiry).toBeDefined()
+      expect(config.secretKey).toBeDefined()
+    })
+  })
+
+  describe('getUploadConfig', () => {
+    it('should return upload config with namespace', () => {
+      const config = getUploadConfig(testNamespace)
+      expect(config.uploadDir).toContain(testNamespace)
+      expect(config.maxFileSize).toBe(10 * 1024 * 1024)
+      expect(config.allowedMimeTypes).toBeDefined()
+      expect(config.allowedExtensions).toBeDefined()
+    })
+
+    it('should allow config overrides', () => {
+      const config = getUploadConfig(testNamespace, {
+        maxFileSize: 5 * 1024 * 1024,
+        allowedMimeTypes: ['image/jpeg'],
+      })
+      expect(config.maxFileSize).toBe(5 * 1024 * 1024)
+      expect(config.allowedMimeTypes).toEqual(['image/jpeg'])
+    })
+  })
+
+  describe('validateFile', () => {
+    it('should validate valid file', () => {
+      const config = getUploadConfig(testNamespace)
+      const result = validateFile({ name: 'test.jpg', type: 'image/jpeg', size: 1024 }, config)
+      expect(result.valid).toBe(true)
+    })
+
+    it('should reject file exceeding max size', () => {
+      const config = getUploadConfig(testNamespace)
+      const result = validateFile(
+        { name: 'test.jpg', type: 'image/jpeg', size: 100 * 1024 * 1024 },
+        config
+      )
+      expect(result.valid).toBe(false)
+      expect(result.error).toContain('File size exceeds')
+    })
+
+    it('should reject file with invalid mime type', () => {
+      const config = getUploadConfig(testNamespace)
+      const result = validateFile(
+        { name: 'test.exe', type: 'application/x-msdownload', size: 1024 },
+        config
+      )
+      expect(result.valid).toBe(false)
+      expect(result.error).toContain('File type')
+    })
+
+    it('should reject file with invalid extension', () => {
+      const config = getUploadConfig(testNamespace)
+      const result = validateFile({ name: 'test.bat', type: 'text/plain', size: 1024 }, config)
+      expect(result.valid).toBe(false)
+      expect(result.error).toContain('File extension')
+    })
+  })
+
+  describe('cleanupTempFiles', () => {
+    it('should cleanup expired temp files', async () => {
+      const result = await cleanupTempFiles()
+      expect(result).toHaveProperty('deleted')
+      expect(result).toHaveProperty('errors')
+      expect(typeof result.deleted).toBe('number')
+      expect(typeof result.errors).toBe('number')
+    })
+  })
+})

package/template/src/server/module-file/module.ts

@@ -0,0 +1,28 @@
+import type { ModuleManifest } from '@shared/core/module-manifest'
+
+const fileManifest: ModuleManifest = {
+  name: 'file',
+  description: 'File upload, storage, and signed URL generation',
+  category: 'system',
+  dependsOn: [],
+
+  routes: {
+    admin: [
+      {
+        importPath: './routes/file-routes',
+        exportName: 'fileRoutes',
+      },
+    ],
+    standalone: {
+      importPath: './routes/file-routes',
+      exportName: 'fileRoutes',
+      mountPath: '/files',
+    },
+  },
+
+  sharedSchemas: {
+    path: 'files',
+  },
+}
+
+export default fileManifest

package/template/src/server/module-file/routes/file-routes.ts

@@ -0,0 +1,288 @@
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import {
+  getFilePath,
+  readFileData,
+  getFileInfo,
+  verifySignature,
+  getPublicFileUrl,
+  getPrivateFileUrl,
+  saveFile,
+} from '@server/utils/file-storage'
+import { mediumRateLimitMiddleware } from '@server/middleware/rate-limit'
+import { successResponse, errorResponse, success } from '@server/utils/route-helpers'
+import { NotFoundError, AuthorizationError } from '@server/utils/app-error'
+import {
+  FileDownloadSchema,
+  PrivateFileQuerySchema,
+  GenerateUrlRequestSchema,
+  FileUrlResponseSchema,
+  UploadResultSchema,
+  UploadFileBodySchema,
+} from '@shared/schemas'
+
+const FileContentSchema = z.any()
+
+const publicFileRoute = createRoute({
+  method: 'get',
+  path: '/public/{namespace}/{filename}',
+  tags: ['files'],
+  request: {
+    params: FileDownloadSchema,
+  },
+  responses: {
+    200: {
+      description: 'File content',
+      content: {
+        'application/octet-stream': {
+          schema: FileContentSchema,
+        },
+      },
+    },
+    404: errorResponse('File not found'),
+  },
+})
+
+const privateFileRoute = createRoute({
+  method: 'get',
+  path: '/private/{namespace}/{filename}',
+  tags: ['files'],
+  request: {
+    params: FileDownloadSchema,
+    query: PrivateFileQuerySchema,
+  },
+  responses: {
+    200: {
+      description: 'File content',
+      content: {
+        'application/octet-stream': {
+          schema: FileContentSchema,
+        },
+      },
+    },
+    403: errorResponse('Invalid or expired signature'),
+    404: errorResponse('File not found'),
+  },
+})
+
+const generateUrlRoute = createRoute({
+  method: 'post',
+  path: '/generate-url',
+  tags: ['files'],
+  request: {
+    body: {
+      content: {
+        'application/json': {
+          schema: GenerateUrlRequestSchema,
+        },
+      },
+    },
+  },
+  responses: {
+    200: successResponse(FileUrlResponseSchema, 'URL generated successfully'),
+    400: errorResponse('Invalid request'),
+    404: errorResponse('File not found'),
+  },
+})
+
+const checkFileRoute = createRoute({
+  method: 'head',
+  path: '/public/{namespace}/{filename}',
+  tags: ['files'],
+  request: {
+    params: FileDownloadSchema,
+  },
+  responses: {
+    200: {
+      description: 'File exists',
+      content: {
+        'application/octet-stream': {
+          schema: z.null(),
+        },
+      },
+    },
+    404: errorResponse('File not found'),
+  },
+})
+
+const checkPrivateFileRoute = createRoute({
+  method: 'head',
+  path: '/private/{namespace}/{filename}',
+  tags: ['files'],
+  request: {
+    params: FileDownloadSchema,
+    query: PrivateFileQuerySchema,
+  },
+  responses: {
+    200: {
+      description: 'File exists',
+      content: {
+        'application/octet-stream': {
+          schema: z.null(),
+        },
+      },
+    },
+    403: errorResponse('Invalid or expired signature'),
+    404: errorResponse('File not found'),
+  },
+})
+
+const uploadFileRoute = createRoute({
+  method: 'post',
+  path: '/upload',
+  tags: ['files'],
+  middleware: [mediumRateLimitMiddleware] as const,
+  request: {
+    body: {
+      content: {
+        'multipart/form-data': {
+          schema: UploadFileBodySchema,
+        },
+      },
+    },
+  },
+  responses: {
+    200: successResponse(UploadResultSchema, 'File uploaded successfully'),
+    400: errorResponse('Invalid file or upload failed'),
+  },
+})
+
+export const fileRoutes = new OpenAPIHono()
+  .openapi(publicFileRoute, async c => {
+    const { namespace, filename } = c.req.valid('param')
+
+    const fileInfo = await getFileInfo(namespace, filename)
+    if (!fileInfo) {
+      throw new NotFoundError('File', `${namespace}/${filename}`)
+    }
+
+    const filePath = getFilePath(namespace, filename)
+    const fileData = await readFileData(filePath)
+
+    c.header('Content-Type', fileInfo.mimeType)
+    c.header('Content-Length', fileInfo.size.toString())
+    c.header('Content-Disposition', `inline; filename="${filename}"`)
+    c.header('Cache-Control', 'public, max-age=31536000')
+    c.header('Last-Modified', fileInfo.lastModified.toUTCString())
+
+    return c.body(fileData as unknown as ReadableStream)
+  })
+  .openapi(privateFileRoute, async c => {
+    const { namespace, filename } = c.req.valid('param')
+    const { expiry, signature } = c.req.valid('query')
+
+    const now = Math.floor(Date.now() / 1000)
+    if (now > expiry) {
+      throw new AuthorizationError('URL has expired')
+    }
+
+    if (!verifySignature(namespace, filename, expiry, signature)) {
+      throw new AuthorizationError('Invalid signature')
+    }
+
+    const fileInfo = await getFileInfo(namespace, filename)
+    if (!fileInfo) {
+      throw new NotFoundError('File', `${namespace}/${filename}`)
+    }
+
+    const filePath = getFilePath(namespace, filename)
+    const fileData = await readFileData(filePath)
+
+    c.header('Content-Type', fileInfo.mimeType)
+    c.header('Content-Length', fileInfo.size.toString())
+    c.header('Content-Disposition', `inline; filename="${filename}"`)
+    c.header('Cache-Control', 'private, no-store')
+
+    return c.body(fileData as unknown as ReadableStream)
+  })
+  .openapi(generateUrlRoute, async c => {
+    const { namespace, filename, isPrivate, expirySeconds } = c.req.valid('json')
+
+    const fileInfo = await getFileInfo(namespace, filename)
+    if (!fileInfo) {
+      throw new NotFoundError('File', `${namespace}/${filename}`)
+    }
+
+    const baseUrl = process.env.PUBLIC_URL || ''
+
+    if (isPrivate) {
+      const { url, expiry } = getPrivateFileUrl(
+        namespace,
+        filename,
+        expirySeconds ?? undefined,
+        baseUrl
+      )
+      return c.json(success({ url, expiry }), 200)
+    }
+
+    const url = getPublicFileUrl(namespace, filename, baseUrl)
+    return c.json(success({ url }), 200)
+  })
+  .openapi(checkFileRoute, async c => {
+    const { namespace, filename } = c.req.valid('param')
+
+    const fileInfo = await getFileInfo(namespace, filename)
+    if (!fileInfo) {
+      throw new NotFoundError('File', `${namespace}/${filename}`)
+    }
+
+    c.header('Content-Type', fileInfo.mimeType)
+    c.header('Content-Length', fileInfo.size.toString())
+    c.header('Last-Modified', fileInfo.lastModified.toUTCString())
+
+    return c.body(null, 200)
+  })
+  .openapi(checkPrivateFileRoute, async c => {
+    const { namespace, filename } = c.req.valid('param')
+    const { expiry, signature } = c.req.valid('query')
+
+    const now = Math.floor(Date.now() / 1000)
+    if (now > expiry) {
+      return c.json({ success: false as const, error: 'URL has expired' }, 403)
+    }
+
+    if (!verifySignature(namespace, filename, expiry, signature)) {
+      return c.json({ success: false as const, error: 'Invalid signature' }, 403)
+    }
+
+    const fileInfo = await getFileInfo(namespace, filename)
+    if (!fileInfo) {
+      throw new NotFoundError('File', `${namespace}/${filename}`)
+    }
+
+    c.header('Content-Type', fileInfo.mimeType)
+    c.header('Content-Length', fileInfo.size.toString())
+
+    return c.body(null, 200)
+  })
+  .openapi(uploadFileRoute, async c => {
+    const body = await c.req.parseBody()
+    const file = body['file']
+
+    if (!file || !(file instanceof File)) {
+      return c.json({ success: false as const, error: 'No file provided' }, 400)
+    }
+
+    const namespace = typeof body['namespace'] === 'string' ? body['namespace'] : 'uploads'
+
+    const arrayBuffer = await file.arrayBuffer()
+    const uploaded = await saveFile(namespace, {
+      name: file.name,
+      type: file.type,
+      size: file.size,
+      data: arrayBuffer,
+    })
+
+    const url = getPublicFileUrl(namespace, uploaded.filename)
+
+    return c.json(
+      success({
+        filename: uploaded.filename,
+        originalName: uploaded.originalName,
+        mimeType: uploaded.mimeType,
+        size: uploaded.size,
+        url,
+      }),
+      200
+    )
+  })