Merge pull request #8492 from sagemathinc/api-admin-project-quotas

next/api/v2: add set-admin-quotas endpoint

Author: williamstein

src/CLAUDE.md

@@ -88,6 +88,13 @@ CoCalc is organized as a monorepo with key packages:
 - **Event Emitters**: Inter-service communication within backend
 - **REST-like APIs**: Some HTTP endpoints for specific operations
 - **API Schema**: API endpoints in `packages/next/pages/api/v2/` use Zod schemas in `packages/next/lib/api/schema/` for validation. These schemas must be kept in harmony with the TypeScript types sent from frontend applications using `apiPost` (in `packages/next/lib/api/post.ts`) or `api` (in `packages/frontend/client/api.ts`). When adding new fields to API requests, both the frontend types and the API schema validation must be updated.
+- **Conat Frontend → Hub Communication**: CoCalc uses a custom distributed messaging system called "Conat" for frontend-to-hub communication:
+  1. **Frontend ConatClient** (`packages/frontend/conat/client.ts`): Manages WebSocket connection to hub, handles authentication, reconnection, and provides API interfaces
+  2. **Core Protocol** (`packages/conat/core/client.ts`): NATS-like pub/sub/request/response messaging with automatic chunking, multiple encoding formats (MsgPack, JSON), and delivery confirmation
+  3. **Hub API Structure** (`packages/conat/hub/api/`): Typed interfaces for different services (system, projects, db, purchases, jupyter) that map function calls to conat subjects
+  4. **Message Flow**: Frontend calls like `hub.projects.setQuotas()` → ConatClient.callHub() → conat request to subject `hub.account.{account_id}.api` → Hub API dispatcher → actual service implementation
+  5. **Authentication**: Each conat request includes account_id and is subject to permission checks at the hub level
+  6. **Subjects**: Messages are routed using hierarchical subjects like `hub.account.{uuid}.{service}` or `project.{uuid}.{compute_server_id}.{service}`
 
 ### Key Technologies
 

src/packages/frontend/cspell.json

@@ -42,7 +42,9 @@
     "tolerations",
     "undelete",
     "undeleting",
-    "revealjs"
+    "revealjs",
+    "conat",
+    "SocketIO"
   ],
   "ignoreWords": [
     "antd",

src/packages/next/lib/api/schema/projects/set-admin-quotas.ts

@@ -0,0 +1,59 @@
+import { z } from "../../framework";
+
+import {
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+} from "../common";
+
+import { ProjectIdSchema } from "./common";
+
+// OpenAPI spec
+//
+export const SetAdminQuotasInputSchema = z
+  .object({
+    project_id: ProjectIdSchema.describe("Project id to set quotas for."),
+    memory_limit: z
+      .number()
+      .nonnegative()
+      .optional()
+      .describe("Memory limit in MB"),
+    memory_request: z
+      .number()
+      .nonnegative()
+      .optional()
+      .describe("Memory request in MB"),
+    cpu_request: z
+      .number()
+      .nonnegative()
+      .optional()
+      .describe("CPU request (number of cores)"),
+    cpu_limit: z
+      .number()
+      .nonnegative()
+      .optional()
+      .describe("CPU limit (number of cores)"),
+    disk_quota: z
+      .number()
+      .nonnegative()
+      .optional()
+      .describe("Disk quota in MB"),
+    idle_timeout: z
+      .number()
+      .nonnegative()
+      .optional()
+      .describe("Idle timeout in seconds"),
+    internet: z.boolean().optional().describe("Internet access"),
+    member_host: z.boolean().optional().describe("Member hosting"),
+    always_running: z.boolean().optional().describe("Always running"),
+  })
+  .describe(
+    "**Administrators only**. Used to set project quotas as an admin. Important: you have to stop and start the project after any change.",
+  );
+
+export const SetAdminQuotasOutputSchema = z.union([
+  FailedAPIOperationSchema,
+  SuccessfulAPIOperationSchema,
+]);
+
+export type SetAdminQuotasInput = z.infer<typeof SetAdminQuotasInputSchema>;
+export type SetAdminQuotasOutput = z.infer<typeof SetAdminQuotasOutputSchema>;

src/packages/next/pages/api/v2/projects/set-admin-quotas.ts

@@ -0,0 +1,88 @@
+/*
+API endpoint to set project quotas as admin.
+
+This requires the user to be an admin.
+*/
+
+import userIsInGroup from "@cocalc/server/accounts/is-in-group";
+import { setQuotas } from "@cocalc/server/conat/api/projects";
+import getAccountId from "lib/account/get-account";
+import { apiRoute, apiRouteOperation } from "lib/api";
+import getParams from "lib/api/get-params";
+import {
+  SetAdminQuotasInputSchema,
+  SetAdminQuotasOutputSchema,
+} from "lib/api/schema/projects/set-admin-quotas";
+import { SuccessStatus } from "lib/api/status";
+
+async function handle(req, res) {
+  try {
+    res.json(await get(req));
+  } catch (err) {
+    res.json({ error: `${err.message}` });
+    return;
+  }
+}
+
+async function get(req) {
+  const account_id = await getAccountId(req);
+  if (account_id == null) {
+    throw Error("must be signed in");
+  }
+  // This user MUST be an admin:
+  if (!(await userIsInGroup(account_id, "admin"))) {
+    throw Error("only admins can set project quotas");
+  }
+
+  const {
+    project_id,
+    memory_limit,
+    memory_request,
+    cpu_request,
+    cpu_limit,
+    disk_quota,
+    idle_timeout,
+    internet,
+    member_host,
+    always_running,
+  } = getParams(req);
+
+  await setQuotas({
+    account_id,
+    project_id,
+    memory: memory_limit,
+    memory_request,
+    cpu_shares:
+      cpu_request != null ? Math.round(cpu_request * 1024) : undefined,
+    cores: cpu_limit,
+    disk_quota,
+    mintime: idle_timeout,
+    network: internet != null ? (internet ? 1 : 0) : undefined,
+    member_host: member_host != null ? (member_host ? 1 : 0) : undefined,
+    always_running:
+      always_running != null ? (always_running ? 1 : 0) : undefined,
+  });
+
+  return SuccessStatus;
+}
+
+export default apiRoute({
+  setAdminQuotas: apiRouteOperation({
+    method: "POST",
+    openApiOperation: {
+      tags: ["Projects", "Admin"],
+    },
+  })
+    .input({
+      contentType: "application/json",
+      body: SetAdminQuotasInputSchema,
+    })
+    .outputs([
+      {
+        status: 200,
+        contentType: "application/json",
+        body: SetAdminQuotasOutputSchema,
+      },
+    ])
+    .handler(handle),
+});

src/packages/server/conat/api/projects.ts

@@ -1,11 +1,13 @@
+import { delay } from "awaiting";
+
 import createProject from "@cocalc/server/projects/create";
 export { createProject };
-import { type UserCopyOptions } from "@cocalc/util/db-schema/projects";
-import { getProject } from "@cocalc/server/projects/control";
-import isCollaborator from "@cocalc/server/projects/is-collaborator";
-import { delay } from "awaiting";
+
+  import isAdmin from "@cocalc/server/accounts/is-admin";
+  import { getProject } from "@cocalc/server/projects/control";
+  import isCollaborator from "@cocalc/server/projects/is-collaborator";
+  import { type UserCopyOptions } from "@cocalc/util/db-schema/projects";
 export * from "@cocalc/server/projects/collaborators";
-import isAdmin from "@cocalc/server/accounts/is-admin";
 
 export async function copyPathBetweenProjects(
   opts: UserCopyOptions,
@@ -45,8 +47,8 @@ async function doCopyPathBetweenProjects(opts: UserCopyOptions) {
   }
 }
 
-import { callback2 } from "@cocalc/util/async-utils";
 import { db } from "@cocalc/database";
+import { callback2 } from "@cocalc/util/async-utils";
 
 export async function setQuotas(opts: {
   account_id: string;
@@ -73,5 +75,3 @@ export async function setQuotas(opts: {
   // @ts-ignore
   await project?.setAllQuotas();
 }
-
-