Merge pull request #7676 from schrodingersket/openapi/compute-server-exec

OpenAPI docs: Added schema for `/api/v2/exec` endpoint for arbitrary project command execution.

Author: williamstein

src/README.md

@@ -192,7 +192,7 @@ There are two types of file system build caching. These greatly improve the time
 It is handy to have a user with admin rights in your dev cocalc server. With the database running you can make a `[email protected]` an admin as follows:
 
 ```sh
-~/cocalc/src$ pnpm run c
+~/cocalc/src$ pnpm install -D express && pnpm run c
 ...
 > db.make_user_admin({email_address:'[email protected]', cb:console.log})
 ...

src/packages/next/lib/api/schema/compute/compute-server-action.ts

@@ -14,7 +14,8 @@ export const ComputeServerActionInputSchema = z
       .describe("Action to be performed on the compute server."),
   })
   .describe(
-    "Perform various action on a specific compute server (e.g., power off, deprovision, etc.).",
+    `Perform various actions on a specific compute server (e.g., power off, deprovision, 
+     etc.).`,
   );
 
 export const ComputeServerActionOutputSchema = z.union([

src/packages/next/lib/api/schema/exec.ts

@@ -0,0 +1,87 @@
+import { z } from "../framework";
+
+import { FailedAPIOperationSchema } from "./common";
+import { ProjectIdSchema } from "./projects/common";
+import { ComputeServerIdSchema } from "./compute/common";
+
+// OpenAPI spec
+//
+export const ExecInputSchema = z
+  .object({
+    project_id: ProjectIdSchema,
+    compute_server_id: ComputeServerIdSchema.describe(
+      `If provided, the desired shell command will be run on the compute server whose id 
+       is specified in this field (if available).`,
+    ).optional(),
+    filesystem: z
+      .boolean()
+      .optional()
+      .describe(
+        `If \`true\`, this shell command runs in the fileserver container on the compute 
+         server; otherwise, it runs on the main compute container.`,
+      ),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        "Path to working directory in which the shell command should be executed.",
+      ),
+    command: z.string().describe("The shell command to execute."),
+    args: z
+      .array(z.string())
+      .optional()
+      .describe("An array of arguments to pass to the shell command."),
+    timeout: z
+      .number()
+      .min(0)
+      .default(60)
+      .optional()
+      .describe("Number of seconds before this shell command times out."),
+    max_output: z
+      .number()
+      .min(0)
+      .optional()
+      .describe("Maximum number of bytes to return from shell command output."),
+    bash: z
+      .boolean()
+      .optional()
+      .describe(
+        `If \`true\`, this command runs in a \`bash\` shell. To do so, the provided shell 
+         command is written to a file and then executed via the \`bash\` command.`,
+      ),
+    aggregate: z
+      .union([
+        z.number(),
+        z.string(),
+        z.object({ value: z.union([z.string(), z.number()]) }),
+      ])
+      .optional()
+      .describe(
+        `If provided, this shell command is aggregated as in 
+         \`src/packages/backend/aggregate.js\`. This parameter allows one to specify
+         multiple callbacks to be executed against the output of the same command 
+         (given identical arguments) within a 60-second window.`,
+      ),
+    err_on_exit: z
+      .boolean()
+      .optional()
+      .describe(
+        `When \`true\`, this call will throw an error whenever the provided shell command 
+       exits with a non-zero exit code.`,
+      ),
+    env: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe(
+        "Environment variables to be passed to the shell command upon execution.",
+      ),
+  })
+  .describe("Perform arbitrary shell commands in a compute server or project.");
+
+export const ExecOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  z.any().describe("Output of executed command."),
+]);
+
+export type ExecInput = z.infer<typeof ExecInputSchema>;
+export type ExecOutput = z.infer<typeof ExecOutputSchema>;

src/packages/next/pages/api/v2/exec.ts

@@ -7,7 +7,10 @@ import getParams from "lib/api/get-params";
 import callProject from "@cocalc/server/projects/call";
 import isCollaborator from "@cocalc/server/projects/is-collaborator";
 
-export default async function handle(req, res) {
+import { apiRoute, apiRouteOperation } from "lib/api";
+import { ExecInputSchema, ExecOutputSchema } from "lib/api/schema/exec";
+
+async function handle(req, res) {
   try {
     res.json(await get(req));
   } catch (err) {
@@ -65,3 +68,24 @@ async function get(req) {
   delete resp.id;
   return resp;
 }
+
+export default apiRoute({
+  exec: apiRouteOperation({
+    method: "POST",
+    openApiOperation: {
+      tags: ["Utils"],
+    },
+  })
+    .input({
+      contentType: "application/json",
+      body: ExecInputSchema,
+    })
+    .outputs([
+      {
+        status: 200,
+        contentType: "application/octet-stream",
+        body: ExecOutputSchema,
+      },
+    ])
+    .handler(handle),
+});