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

package/src/engine/paths/containers.ts

@@ -0,0 +1,304 @@
+import { RouteConfig } from "@asteasolutions/zod-to-openapi";
+import { extractArtifactsRequestSchema, extractArtifactsResponseSchema } from "../images.js";
+import z from "zod";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { runRequestSchema, runResponseSchema } from "../deprecated/run-request.js";
+import { errorResponseSchema } from "../response.js";
+
+extendZodWithOpenApi(z);
+
+export const runContainerRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/containers/run",
+  operationId: "runContainer",
+  summary: "Run a container job (removed — returns 410)",
+  description: "**Removed in v0.2.0.** This endpoint always returns 410 Gone. Use POST /api/v1/sessions with config.auto_cleanup: true and block_until_complete: true instead.",
+  tags: [
+    "containers"
+  ],
+  deprecated: true,
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: runRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    202: {
+      description: "Job accepted and queued",
+      content: {
+        "application/json": {
+          schema: runResponseSchema,
+          example: {
+            job_id: "job-abc123",
+            status: "pending",
+            message: "Job accepted and queued"
+          }
+        }
+      }
+    },
+    400: {
+      description: "Invalid request body or validation failure",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Failed to start job",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const getContainerStatusRouteSchema: RouteConfig = {
+  method: "get",
+  path: "/api/v1/containers/{job_id}",
+  operationId: "getContainerStatus",
+  summary: "Get job status",
+  description: "Returns the current status and output of a container job.",
+  tags: [
+    "containers"
+  ],
+  parameters: [
+    {
+      name: "job_id",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "job-abc123"
+    }
+  ],
+  deprecated: true,
+  responses: {
+    200: {
+      description: "Job found",
+      content: {
+        "application/json": {
+          schema: runResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing job_id",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Job not found",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const cancelContainerRouteSchema: RouteConfig = {
+  method: "delete",
+  path: "/api/v1/containers/{job_id}",
+  operationId: "cancelContainer",
+  summary: "Cancel a running job",
+  description: "Cancels an in-progress container job. No-ops if already completed.",
+  tags: [
+    "containers"
+  ],
+  parameters: [
+    {
+      name: "job_id",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "job-abc123"
+    }
+  ],
+  deprecated: true,
+  responses: {
+    200: {
+      description: "Job cancelled",
+      content: {
+        "application/json": {
+          schema: z.object({
+            job_id: z.string(),
+            message: z.string(),
+          }),
+          example: {
+            job_id: "job-abc123",
+            message: "Job cancelled successfully"
+          }
+        }
+      }
+    },
+    400: {
+      description: "Missing job_id",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Cancel failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const cleanupContainerRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/containers/{job_id}/cleanup",
+  operationId: "cleanupContainer",
+  summary: "Clean up a specific container",
+  description: "Removes the container associated with a job after artifact extraction.",
+  tags: [
+    "containers"
+  ],
+  parameters: [
+    {
+      name: "job_id",
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      example: "job-abc123"
+    }
+  ],
+  deprecated: true,
+  responses: {
+    200: {
+      description: "Container cleaned up",
+      content: {
+        "application/json": {
+          schema: z.object({
+            job_id: z.string(),
+            message: z.string(),
+          }),
+          example: {
+            job_id: "job-abc123",
+            message: "Container cleaned up successfully"
+          }
+        }
+      }
+    },
+    400: {
+      description: "Missing job_id",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Cleanup failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const cleanupOrphanedContainersRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/containers/cleanup",
+  operationId: "cleanupOrphanedContainers",
+  summary: "Clean up all orphaned containers",
+  description: "Removes all Figulus-managed containers that are no longer tracked.",
+  tags: [
+    "containers"
+  ],
+  deprecated: true,
+  responses: {
+    200: {
+      description: "Orphaned containers removed",
+      content: {
+        "application/json": {
+          schema: z.object({
+            removed: z.int().describe("Number of containers removed"),
+            message: z.string(),
+          }),
+        }
+      }
+    },
+    500: {
+      description: "Cleanup failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const extractArtifactsRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/containers/extract",
+  operationId: "extractArtifacts",
+  summary: "Extract files from a container",
+  description: "Copies files from a container path to a host path.",
+  tags: [
+    "containers"
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: extractArtifactsRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    200: {
+      description: "Artifacts extracted",
+      content: {
+        "application/json": {
+          schema: extractArtifactsResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Validation failure",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Extraction failed (container not found, path not found, etc.)",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};

package/src/engine/paths/dry-run.ts

@@ -0,0 +1,44 @@
+import { RouteConfig } from "@asteasolutions/zod-to-openapi";
+import { runRequestSchema } from "../deprecated/run-request.js";
+import { dryRunResponseSchema } from "../dry-run.js";
+import { errorResponseSchema } from "../response.js";
+
+export const dryRunContainerRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/dryRun",
+  operationId: "dryRunContainer",
+  summary: "Dry-run a container command",
+  description: "Returns the resolved final command without executing it. Requires image and command fields; other RunRequest fields are optional.",
+  tags: [
+    "containers"
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: runRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    200: {
+      description: "Resolved command",
+      content: {
+        "application/json": {
+          schema: dryRunResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Missing image or command",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};

package/src/engine/paths/health.ts

@@ -0,0 +1,37 @@
+import { RouteConfig } from "@asteasolutions/zod-to-openapi";
+import { healthResponseSchema } from "../health.js";
+
+export const healthRouteSchema: RouteConfig = {
+    method: "get",
+    path: "/health",
+    operationId: "getHealth",
+    summary: "Engine health check",
+    description: "Returns engine health and Docker connectivity status. Returns 503 if the Docker daemon is unreachable.",
+    tags: ["health"],
+    responses: {
+        200: {
+            description: "Engine is healthy",
+            content: {
+                "application/json": {
+                    schema: healthResponseSchema,
+                    example: {
+                        status: "healthy",
+                        docker_api: "1.47",
+                    },
+                },
+            },
+        },
+        503: {
+            description: "Docker daemon unreachable",
+            content: {
+                "application/json": {
+                    schema: healthResponseSchema,
+                    example: {
+                        status: "unhealthy",
+                        message: "Docker daemon unreachable: connection refused"
+                    }
+                }
+            }
+        }
+    }
+}

package/src/engine/paths/images.ts

@@ -0,0 +1,148 @@
+import { RouteConfig } from "@asteasolutions/zod-to-openapi";
+import z from "zod";
+import { buildImageRequestSchema, buildImageResponseSchema, pruneImagesRequestSchema, pruneImagesResponseSchema } from "../images.js";
+import { bigIntSchema } from "../../core/primitives.js";
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { errorResponseSchema } from "../response.js";
+
+extendZodWithOpenApi(z);
+
+export const buildImageRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/images/build",
+  operationId: "buildImage",
+  summary: "Build a Docker image from a RunnerParts spec",
+  description: "Content-addressable image build. Returns immediately with a cache hit if the spec hash matches an existing image; otherwise builds and pushes.",
+  tags: [
+    "images"
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: buildImageRequestSchema
+        }
+      },
+      required: true
+    }
+  },
+  responses: {
+    200: {
+      description: "Image built or found in cache",
+      content: {
+        "application/json": {
+          schema: buildImageResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Invalid spec or request",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "Build or push failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const pruneImagesRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/images/prune",
+  operationId: "pruneImages",
+  summary: "Garbage-collect unused Figulus images",
+  description: "Removes images that have not been used within the retention window. When `all` is true, also prunes all unused Docker images (equivalent to `docker image prune -a`).",
+  tags: [
+    "images"
+  ],
+  parameters: [
+    {
+      name: "retention_days",
+      in: "query",
+      required: false,
+      schema: {
+        type: "integer",
+        minimum: 1,
+        default: 30
+      },
+      description: "Images unused for longer than this many days are removed"
+    }
+  ],
+  request: {
+    body: {
+      description: undefined,
+      content: {
+        "application/json": {
+          schema: pruneImagesRequestSchema
+        }
+      },
+      required: false
+    }
+  },
+  responses: {
+    200: {
+      description: "GC completed",
+      content: {
+        "application/json": {
+          schema: pruneImagesResponseSchema
+        }
+      }
+    },
+    400: {
+      description: "Invalid retention_days value",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    },
+    500: {
+      description: "GC failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};
+
+export const pruneCacheRouteSchema: RouteConfig = {
+  method: "post",
+  path: "/api/v1/images/prune-cache",
+  operationId: "pruneCache",
+  summary: "Prune Docker build cache",
+  description: "Removes all unused Docker build cache entries. Equivalent to `docker buildx prune -a`.",
+  tags: [
+    "images"
+  ],
+  responses: {
+    200: {
+      description: "Build cache pruned",
+      content: {
+        "application/json": {
+          schema: z.object({
+            freed_bytes: bigIntSchema.describe("Bytes freed from build cache")
+          })
+        }
+      }
+    },
+    500: {
+      description: "Prune failed",
+      content: {
+        "application/json": {
+          schema: errorResponseSchema
+        }
+      }
+    }
+  }
+};

package/src/engine/paths/index.ts

@@ -0,0 +1,7 @@
+export * from './containers.js';
+export * from './dry-run.js';
+export * from './health.js';
+export * from './images.js';
+export * from './sessions.js';
+export * from './stacks.js';
+export * from './volumes.js';