feat: IPFS API draft

Author: imiskii

backend/ipfs/TaskBoardIPFS.ts

@@ -13,21 +13,31 @@ const dotenv = require('dotenv')
 // Load env variables
 dotenv.config()
 
+// Singletone pattern
 export class TaskBoardIPFS {
+  private static instance: TaskBoardIPFS
   private ipfs: HeliaIPFSClient
 
-  constructor () {
+  private constructor () {
     this.ipfs = new HeliaIPFSClient({
       mode: (process.env.IPFS_STORAGE_MODE! as IPFSMode) || IPFSMode.DEVELOPMENT,
       localIPFSApiUrl: process.env.IPFS_LOCAL_API_URL!,
       localIPFSGatewayUrl: process.env.IPFS_LOCAL_GATEWAY_URL!
     })
   }
 
+  static getInstance(): TaskBoardIPFS {
+    if (!TaskBoardIPFS.instance) {
+      TaskBoardIPFS.instance = new TaskBoardIPFS()
+    }
+    return TaskBoardIPFS.instance
+  }
+
   /**
    * Upload task to IPFS
    * @param task task to be uploaded. This mutates `ipfsCid` and `createdAt` attributes of the task!
    * @returns identifier of task
+   * @throws if upload was not successful.
    */
   public async publishTask(task: Task): Promise<string> {
     try {
@@ -45,6 +55,12 @@ export class TaskBoardIPFS {
     }
   }
 
+  /**
+   * Download task from IPFS
+   * @param cid identifier of task
+   * @returns object representing the received task.
+   * @throws if download was not successful.
+   */
   public async loadTaskFromIPFS(cid: string): Promise<Task> {
     try {
       const taskBytes = await this.ipfs.download(cid)
@@ -60,4 +76,6 @@ export class TaskBoardIPFS {
       throw new Error(`Failed to load task from IPFS ${cid}: ${error}`)
     }
   }
+
+  /// TODO: Unpin task from IPFS
 }

backend/package.json

@@ -12,6 +12,8 @@
   "license": "ISC",
   "description": "",
   "dependencies": {
+    "@fastify/swagger": "^9.5.1",
+    "@fastify/swagger-ui": "^5.2.3",
     "@helia/http": "^2.2.1",
     "@helia/unixfs": "^5.1.0",
     "@sinclair/typebox": "^0.34.39",

backend/src/TaskManager.ts

@@ -0,0 +1,31 @@
+import { TaskBoardIPFS } from "../ipfs/TaskBoardIPFS"
+import { Task } from "../../objects/BoardTask"
+
+
+class TaskManager{
+  private ipfs: TaskBoardIPFS
+
+  constructor() {
+    this.ipfs = TaskBoardIPFS.getInstance()
+  }
+
+  async addTask(task: Task): Promise<string> {
+    // Here: actually upload to IPFS using Helia/Web3.Storage/etc.
+    // return the CID
+    const cid = 'QmFakeCID' + Date.now() // placeholder
+    task.ipfsCid = cid
+    return cid
+  }
+
+  async getTasks(limit: number, offset: number, filters?: Partial<Task>): Promise<Task[]> {
+    // TODO: Later, hook into DB/cache/Graph
+    return []
+  }
+
+  async deleteTask(cid: string): Promise<void> {
+    // TODO: Call unpin API
+  }
+
+}
+
+export default TaskManager

backend/src/app.ts

@@ -1,4 +1,6 @@
 import Fastify from "fastify";
+import fastifySwagger from '@fastify/swagger'
+import fastifySwaggerUi from '@fastify/swagger-ui'
 const dotenv = require('dotenv')
 
 // Load env variables
@@ -7,9 +9,26 @@ dotenv.config()
 
 const app = Fastify({ logger: true })
 
+// Swagger for API documentation
+app.register(fastifySwagger, {
+  swagger: {
+    info: {
+      title: 'CTF Backend API',
+      description: 'API docs for CTF challenge backend',
+      version: '0.1.0'
+    }
+  }
+})
+
+app.register(fastifySwaggerUi, {
+  routePrefix: '/docs',
+  uiConfig: { docExpansion: 'full', deepLinking: false }
+})
+
+
 // Register routes
-import ipfsRoutes from "./routes/ipfsRoutes";
-app.register(ipfsRoutes, { prefix: '/api/ipfs' })
+import taskRoutes from "./routes/taskRoutes";
+app.register(taskRoutes, { prefix: '/api' })
 
 // Start server
 const start = async () => {

backend/src/controllers/ipfsController.ts

@@ -0,0 +1,40 @@
+import { type FastifyReply, type FastifyRequest } from 'fastify';
+import { type Static } from '@sinclair/typebox'
+import { TaskSchema } from '../schemas/taskSchema'
+import TaskManager from '../TaskManager'
+import { Task } from '../../../objects/BoardTask';
+
+type TaskBody = Static<typeof TaskSchema>
+
+const IPFS = new TaskManager()
+
+export async function createTaskController(
+  request: FastifyRequest<{ Body: TaskBody }>,
+  reply: FastifyReply
+) {
+  const task = new Task(request.body)
+  const cid = await IPFS.addTask(task)
+  reply.code(201).send({ ...task.toJSON(), createdAt: task.createdAt, ipfsCid: cid })
+}
+
+
+export async function getTasksController(
+  request: FastifyRequest<{ Querystring: { limit?: number; offset?: number; difficulty?: string } }>,
+  reply: FastifyReply
+) {
+  const { limit = 10, offset = 0, difficulty } = request.query
+  const filters: any = {}
+  if (difficulty) filters.difficulty = difficulty
+
+  const tasks = await IPFS.getTasks(limit, offset, filters)
+  reply.send(tasks.map(t => ({ ...t.toJSON(), createdAt: t.createdAt, ipfsCid: t.ipfsCid })))
+}
+
+
+export async function deleteTaskController(
+  request: FastifyRequest<{ Params: { cid: string } }>,
+  reply: FastifyReply
+) {
+  await IPFS.deleteTask(request.params.cid)
+  reply.code(204).send()
+}

backend/src/controllers/taskController.ts

@@ -0,0 +1,46 @@
+import { type FastifyPluginAsync } from 'fastify';
+import { TaskResponseSchema, TaskSchema } from '../schemas/taskSchema'
+import { createTaskController, deleteTaskController, getTasksController } from '../controllers/taskController'
+
+const taskRoutes: FastifyPluginAsync = async (app) => {
+  
+  app.get('/tasks', {
+    schema: {
+      querystring: {
+        type: 'object',
+        properties: {
+          limit: { type: 'integer', minimum: 1, maximum: 50 },
+          offset: { type: 'integer', minimum: 0 },
+          difficulty: { type: 'string' }
+        }
+      },
+      response: {
+        200: { type: 'array', items: TaskResponseSchema }
+      }
+    },
+    handler: getTasksController
+  })
+
+  app.post('/tasks', {
+    schema: {
+      body: TaskSchema,
+      response: {
+        201: TaskResponseSchema
+      }
+    },
+    handler: createTaskController
+  })
+
+  app.delete('/tasks/:cid', {
+    schema: {
+      params: {
+        type: 'object',
+        required: ['cid'],
+        properties: { cid: { type: 'string' } }
+      }
+    },
+    handler: deleteTaskController
+  })
+}
+
+export default taskRoutes;

backend/src/routes/ipfsRoutes.ts

@@ -0,0 +1,27 @@
+import { Type } from '@sinclair/typebox'
+
+export const TaskDifficultySchema = Type.Union([
+  Type.Literal('Beginner'),
+  Type.Literal('Easy'),
+  Type.Literal('Medium'),
+  Type.Literal('Hard'),
+  Type.Literal('Expert')
+])
+
+export const TaskSchema = Type.Object({
+  title: Type.String({ minLength: 3 }),
+  description: Type.String({ minLength: 0 }),
+  difficulty: TaskDifficultySchema,
+  tags: Type.Array(Type.String(), { default: [] }),
+  createdBy: Type.String(),
+  requirements: Type.Optional(Type.Array(Type.String())),
+  resources: Type.Optional(Type.Array(Type.String()))
+})
+
+export const TaskResponseSchema = Type.Intersect([
+  TaskSchema,
+  Type.Object({
+    createdAt: Type.Number(),
+    ipfsCid: Type.Optional(Type.String())
+  })
+])