@figulus/schema 0.4.0-alpha-dev → 0.5.0-alpha-dev-2

package/src/engine/paths/sessions.ts

@@ -0,0 +1,493 @@
+import { RouteConfig } from "@asteasolutions/zod-to-openapi";
+import z from "zod";
+import { createSessionRequestSchema, createSessionResponseSchema, getRunResponseSchema, getSessionResponseSchema, listRunsResponseSchema, runInSessionRequestSchema, runInSessionResponseSchema, syncFileRequestSchema, syncFileResponseSchema } from "../sessions.js";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { errorResponseSchema } from "../response.js";
+
+extendZodWithOpenApi(z);
+
+export const listSessionsRouteSchema: RouteConfig = {
+  method: "get",
+  path: "/api/v1/sessions",
+  operationId: "listSessions",
+  summary: "List all active sessions",
+  description: "Returns all active sessions from the session store (memory and Valkey).",
+  tags: [
+    "sessions"
+  ],
+  responses: {
+    200: {
+      description: "List of active sessions",
+      content: {
+        "application/json": {
+          schema: z.object({
+            sessions: getSessionResponseSchema.array(),
+            count: z.int(),
+          })
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable (Valkey not configured)",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const createSessionRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/sessions",
+  operationId: "createSession",
+  summary: "Create a persistent session",
+  description: "Creates and starts a persistent container session. Returns 503 if Valkey is not configured (session management unavailable).",
+  tags: [
+    "sessions"
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: createSessionRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    201: {
+      description: "Session created",
+      content: {
+        "application/json": {
+          schema: createSessionResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing image_tag or invalid request",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Failed to create session",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable (Valkey not configured)",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const getSessionRouteSchema: RouteConfig = {
+  method: "get",
+  path: "/api/v1/sessions/{sessionId}",
+  operationId: "getSession",
+  summary: "Get session details",
+  description: "Returns the current status and metadata for a session, with container liveness verification.",
+  tags: [
+    "sessions"
+  ],
+  parameters: [
+    {
+      name: "sessionId",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "sess-abc123"
+    }
+  ],
+  responses: {
+    200: {
+      description: "Session details",
+      content: {
+        "application/json": {
+          schema: getSessionResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing sessionId",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Session not found",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const deleteSessionRouteSchema: RouteConfig = {
+  method: "delete",
+  path: "/api/v1/sessions/{sessionId}",
+  operationId: "deleteSession",
+  summary: "Delete a session",
+  description: "Destroys the session and its container.",
+  tags: [
+    "sessions"
+  ],
+  parameters: [
+    {
+      name: "sessionId",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "sess-abc123"
+    }
+  ],
+  responses: {
+    200: {
+      description: "Session deleted",
+      content: {
+        "application/json": {
+          schema: z.object({
+            message: z.string(),
+            session_id: z.string(),
+          }),
+          example: {
+            message: "Session deleted successfully",
+            session_id: "sess-abc123"
+          }
+        }
+      }
+    },
+    400: {
+      description: "Missing sessionId",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Session not found",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const runInSessionRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/sessions/{sessionId}/run",
+  operationId: "runInSession",
+  summary: "Run a command in a session",
+  description: "Executes a command inside the session container and returns the result. Blocks until command completes or timeout is reached.",
+  tags: [
+    "sessions"
+  ],
+  parameters: [
+    {
+      name: "sessionId",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "sess-abc123"
+    }
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: runInSessionRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    200: {
+      description: "Command completed",
+      content: {
+        "application/json": {
+          schema: runInSessionResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing command or invalid request",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Session not found",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Run failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const syncFileInSessionRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/sessions/{sessionId}/sync-file",
+  operationId: "syncFileInSession",
+  summary: "Sync a file into a session container",
+  description: "Writes a file to an absolute path inside the running session container. Content must be base64-encoded (default) or utf8 as specified by encoding.",
+  tags: [
+    "sessions"
+  ],
+  parameters: [
+    {
+      name: "sessionId",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "sess-abc123"
+    }
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: syncFileRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    200: {
+      description: "File written successfully",
+      content: {
+        "application/json": {
+          schema: syncFileResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing targetPath/content, invalid encoding, invalid base64, or invalid path",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Session not found",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    409: {
+      description: "Container is no longer running",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "File write failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const listSessionRunsRouteSchema: RouteConfig = {
+  method: "get",
+  path: "/api/v1/sessions/{sessionId}/runs",
+  operationId: "listSessionRuns",
+  summary: "List all runs for a session",
+  description: "Returns all cached runs for a session, ordered by start time ascending.",
+  tags: [
+    "sessions"
+  ],
+  parameters: [
+    {
+      name: "sessionId",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "sess-abc123"
+    }
+  ],
+  responses: {
+    200: {
+      description: "List of runs",
+      content: {
+        "application/json": {
+          schema: listRunsResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing sessionId",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Internal error",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const getSessionRunRouteSchema: RouteConfig = {
+  method: "get",
+  path: "/api/v1/sessions/{sessionId}/runs/{runId}",
+  operationId: "getSessionRun",
+  summary: "Get a previous run result",
+  description: "Retrieves the stored result of a past run within a session.",
+  tags: [
+    "sessions"
+  ],
+  parameters: [
+    {
+      name: "sessionId",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "sess-abc123"
+    },
+    {
+      name: "runId",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "run-def456"
+    }
+  ],
+  responses: {
+    200: {
+      description: "Run details",
+      content: {
+        "application/json": {
+          schema: getRunResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing runId",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Run not found",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Session management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};

package/src/engine/paths/stacks.ts

@@ -0,0 +1,179 @@
+import { RouteConfig } from "@asteasolutions/zod-to-openapi";
+import { getStackResponseSchema, listStacksResponseSchema, startStackRequestSchema, startStackResponseSchema } from "../sessions.js";
+import { errorResponseSchema } from "../response.js";
+
+export const startStackRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/stacks",
+  operationId: "startStack",
+  summary: "Start a FigStack",
+  description: "Parse the FigStack spec and start all containers in dependency order. Optionally builds all required images first if build=true.",
+  tags: [
+    "stacks"
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: startStackRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    201: {
+      description: "Stack started successfully",
+      content: {
+        "application/json": {
+          schema: startStackResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Invalid request or spec",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Stack startup failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Stack management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const listStacksRouteSchema: RouteConfig = {
+  method: "get",
+  path: "/api/v1/stacks",
+  operationId: "listStacks",
+  summary: "List all running FigStacks",
+  description: "Returns all stacks currently tracked by the engine.",
+  tags: [
+    "stacks"
+  ],
+  responses: {
+    200: {
+      description: "List of running stacks",
+      content: {
+        "application/json": {
+          schema: listStacksResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Stack management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const getStackRouteSchema: RouteConfig = {
+  method: "get",
+  path: "/api/v1/stacks/{stackName}",
+  operationId: "getStack",
+  summary: "Get the status of a running FigStack",
+  description: "Returns the current status of all containers in the named stack.",
+  tags: [
+    "stacks"
+  ],
+  parameters: [
+    {
+      name: "stackName",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "blog"
+    }
+  ],
+  responses: {
+    200: {
+      description: "Stack status",
+      content: {
+        "application/json": {
+          schema: getStackResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Stack not found",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Stack management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const stopStackRouteSchema: RouteConfig = {
+  method: "delete",
+  path: "/api/v1/stacks/{stackName}",
+  operationId: "stopStack",
+  summary: "Stop a running FigStack",
+  description: "Stops all containers in the stack and removes the stack network.",
+  tags: [
+    "stacks"
+  ],
+  parameters: [
+    {
+      name: "stackName",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "blog"
+    }
+  ],
+  responses: {
+    204: {
+      description: "Stack stopped successfully"
+    },
+    500: {
+      description: "Stack stop failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Stack management unavailable",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};