Skip to content

Commit 2f218a2

Browse files
williamsteinwilliamstein
authored
Merge pull request #7618 from schrodingersket/openapi/compute
OpenAPI doc: Completed first draft of Compute Server docs.
2 parents 23b3844 + 8fc8a27 commit 2f218a2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+2110
-172
lines changed

‎src/packages/next/lib/api/latex.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
export const DEFAULT_LATEX_COMMAND =
2+
"latexmk -pdf -f -g -bibtex -deps -interaction=nonstopmode";

‎src/packages/next/lib/api/schema/accounts/common.ts

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import { z } from "../../framework";
2+
3+
export const AccountIdSchema = z
4+
.string()
5+
.uuid()
6+
.describe("Account id.");
7+
8+
export type AccountId = z.infer<typeof AccountIdSchema>;

‎src/packages/next/lib/api/schema/common.ts

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import { z } from "../framework";
2+
3+
export const SuccessfulAPIOperationSchema = z
4+
.object({
5+
status: z.enum(["ok"])
6+
.describe(
7+
`Indicates the status of this operation; if the operation was successful, the
8+
value of this field is always set to \`"ok"\`.`
9+
)
10+
});
11+
12+
export const FailedAPIOperationSchema = z
13+
.object({
14+
error: z
15+
.string()
16+
.describe("Error message if something goes badly wrong."),
17+
});
18+
19+
20+
export type FailedAPIOperation = z.infer<typeof FailedAPIOperationSchema>;
21+
export type SuccessfulAPIOperation = z.infer<typeof SuccessfulAPIOperationSchema>;

‎src/packages/next/lib/api/schema/compute/check-in.ts

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import { z } from "../../framework";
2+
3+
import { FailedAPIOperationSchema } from "../common";
4+
5+
import { ComputeServerIdBodySchema } from "./common";
6+
7+
const VpnSha1Schema = z
8+
.string()
9+
.describe("SHA1 VPN hash")
10+
.optional();
11+
12+
const StorageSha1Schema = z
13+
.string()
14+
.describe("SHA-1 storage hash")
15+
.optional();
16+
17+
// OpenAPI spec
18+
//
19+
export const ComputeServerCheckInInputSchema = z
20+
.object({
21+
id: ComputeServerIdBodySchema,
22+
vpn_sha1: VpnSha1Schema,
23+
storage_sha1: StorageSha1Schema,
24+
})
25+
.describe(
26+
`Used by compute servers to periodically checking in with CoCalc using a project api
27+
key.`,
28+
);
29+
30+
export const ComputeServerCheckInOutputSchema = z.union([
31+
FailedAPIOperationSchema,
32+
z.object({
33+
vpn: z
34+
.object({
35+
image: z
36+
.string()
37+
.describe("VPN image name and tag."),
38+
nodes: z.array(z.object({
39+
})),
40+
}),
41+
storage: z.array(z.object({
42+
})),
43+
vpn_sha1: VpnSha1Schema,
44+
storage_sha1: StorageSha1Schema,
45+
}),
46+
]);
47+
48+
export type ComputeServerCheckInInput = z.infer<typeof ComputeServerCheckInInputSchema>;
49+
export type ComputeServerCheckInOutput = z.infer<typeof ComputeServerCheckInOutputSchema>;

‎src/packages/next/lib/api/schema/compute/common.ts

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
import { z } from "../../framework";
2+
3+
export const ComputeServerIdBodySchema = z
4+
.number()
5+
.int()
6+
.min(0)
7+
.describe("**Integer** compute server id.");
8+
9+
export const ComputeServerIdQueryParamSchema = z
10+
.string()
11+
.describe("**String** compute server id.");
12+
13+
export const ServerImageNoCacheQueryParamSchema = z
14+
.object({
15+
noCache: z
16+
.string()
17+
.describe("**Administrators only**. Disables database caching for this query.")
18+
.optional(),
19+
});
20+
21+
export const ComputeServerStateSchema = z
22+
.enum([
23+
"deprovisioned",
24+
"off",
25+
"running",
26+
"starting",
27+
"stopping",
28+
"suspended",
29+
"suspending",
30+
"unknown",
31+
])
32+
.describe("The state of the compute server.");
33+
34+
export const ComputeServerColorSchema = z
35+
.string()
36+
.describe(
37+
`Compute server color in rgb(#,#,#) format. Used for color-coding compute servers in
38+
the CoCalc UI.`,
39+
);
40+
41+
export const ComputeServerTitleSchema = z
42+
.string()
43+
.describe(
44+
`Title of this compute server. Used purely to make it easier for the user to keep
45+
track of it.`
46+
);
47+
48+
export const ComputeServerCloudSchema = z
49+
.enum([
50+
"google-cloud",
51+
"hyperstack",
52+
"onprem",
53+
])
54+
.describe("The cloud provider used to run this compute server");
55+
56+
export const ComputeServerImageProxySchema = z
57+
.object({
58+
path: z
59+
.string(),
60+
target: z
61+
.string(),
62+
ws: z
63+
.boolean()
64+
.optional(),
65+
app: z
66+
.string()
67+
.optional(),
68+
name: z
69+
.string()
70+
.optional(),
71+
})
72+
73+
export const GoogleCloudServerConfigurationSchema = z
74+
.object({});
75+
76+
export const HyperstackServerConfigurationSchema = z
77+
.object({});
78+
79+
export const ServerConfigurationSchema = z
80+
.union([
81+
GoogleCloudServerConfigurationSchema,
82+
HyperstackServerConfigurationSchema,
83+
]);
84+
85+
export const BaseServerConfigurationSchema = z
86+
.object({
87+
cloud: ComputeServerCloudSchema,
88+
dns: z
89+
.string()
90+
.describe("DNS name"),
91+
spot: z
92+
.boolean()
93+
.describe("If true, provision a spot instance."),
94+
zone: z
95+
.string()
96+
.describe("Cloud provider zone to which this template defaults."),
97+
image: z
98+
.string()
99+
.describe("Compute server template image name."),
100+
region: z
101+
.string()
102+
.describe("Compute server template region name."),
103+
ephemeral: z
104+
.boolean()
105+
.describe("Indicates whether the compute server is ephemeral.")
106+
.optional(),
107+
diskType: z
108+
.string()
109+
.describe("Compute server template disk type."),
110+
diskSizeGb: z
111+
.number()
112+
.min(0)
113+
.describe("Compute server template disk image size in GB."),
114+
externalIp: z
115+
.boolean()
116+
.describe(
117+
`When true, the compute server is configured with an external IP address.`
118+
),
119+
tag_cocalc: z
120+
.string()
121+
.describe("CoCalc tag"),
122+
machineType: z
123+
.string()
124+
.describe(
125+
"Cloud-specific machine type for this template (e.g., `t2d-standard-1`)."
126+
),
127+
excludeFromSync: z
128+
.array(z.string())
129+
.describe("Array of top level directories to exclude from sync."),
130+
acceleratorType: z
131+
.string()
132+
.describe(
133+
"Number of hardware accelerators to be provisioned to this server."
134+
)
135+
.optional(),
136+
acceleratorCount: z
137+
.number()
138+
.int()
139+
.min(0)
140+
.describe(
141+
"Number of hardware accelerators to be provisioned with this server."
142+
)
143+
.optional(),
144+
proxy: ComputeServerImageProxySchema
145+
.optional()
146+
});
147+
148+
export type BaseServerConfiguration = z.infer<typeof BaseServerConfigurationSchema>;
149+
export type ComputeServerBodyId = z.infer<typeof ComputeServerIdBodySchema>;
150+
export type ComputeServerCloud = z.infer<typeof ComputeServerCloudSchema>;
151+
export type ComputeServerColor = z.infer<typeof ComputeServerColorSchema>;
152+
export type ComputeServerImageProxy = z.infer<typeof ComputeServerImageProxySchema>;
153+
export type ComputeServerQueryParamId = z.infer<typeof ComputeServerIdBodySchema>;
154+
export type ComputeServerState = z.infer<typeof ComputeServerStateSchema>;
155+
export type ComputeServerTitle = z.infer<typeof ComputeServerTitleSchema>;
156+
export type GoogleCloudServerConfiguration = z.infer<typeof GoogleCloudServerConfigurationSchema>;
157+
export type HyperstackServerConfiguration = z.infer<typeof HyperstackServerConfigurationSchema>;
158+
export type ServerConfiguration = z.infer<typeof ServerConfigurationSchema>;
159+
export type ServerImageNoCache = z.infer<typeof ServerImageNoCacheQueryParamSchema>;

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import { z } from "../../framework";
2+
3+
import { FailedAPIOperationSchema } from "../common";
4+
5+
import { ComputeServerIdBodySchema } from "./common";
6+
7+
// OpenAPI spec
8+
//
9+
export const ComputeServerActionInputSchema = z
10+
.object({
11+
id: ComputeServerIdBodySchema,
12+
action: z
13+
.enum([
14+
"start",
15+
"stop",
16+
"reboot",
17+
"suspend",
18+
"resume",
19+
"deprovision",
20+
])
21+
.describe("Action to be performed on the compute server."),
22+
})
23+
.describe(
24+
"Perform various action on a specific compute server (e.g., power off, deprovision, etc.)."
25+
);
26+
27+
export const ComputeServerActionOutputSchema = z.union([
28+
FailedAPIOperationSchema,
29+
z.object({
30+
result: z
31+
.array(z.string())
32+
.describe(
33+
"List of likely guesses for the type of code, from most likely to less likely.",
34+
),
35+
}),
36+
]);
37+
38+
export type ComputeServerActionInput = z.infer<typeof ComputeServerActionInputSchema>;
39+
export type ComputeServerActionOutput = z.infer<typeof ComputeServerActionOutputSchema>;

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

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import { z } from "../../framework";
2+
3+
import { FailedAPIOperationSchema } from "../common";
4+
5+
import { ProjectIdSchema } from "../projects/common";
6+
7+
import {
8+
ComputeServerCloudSchema,
9+
ComputeServerColorSchema,
10+
ComputeServerIdBodySchema,
11+
ComputeServerTitleSchema,
12+
ServerConfigurationSchema
13+
} from "./common";
14+
15+
// OpenAPI spec
16+
//
17+
export const CreateServerInputSchema = z
18+
.object({
19+
configuration: ServerConfigurationSchema,
20+
title: ComputeServerTitleSchema,
21+
color: ComputeServerColorSchema,
22+
cloud: ComputeServerCloudSchema,
23+
project_id: ProjectIdSchema
24+
.describe(
25+
"The project id that this compute server provides compute for."
26+
),
27+
idle_timeout: z
28+
.number()
29+
.describe(
30+
`The idle timeout in seconds of this compute server. If set to 0, the server will
31+
never turn off automatically. The compute server idle timeouts if none of the tabs
32+
it is providing are actively touched through the web UI. _Not yet implemented._`
33+
)
34+
.optional(),
35+
autorestart: z.boolean()
36+
.describe(
37+
`If true and the compute server stops for any reason, then it
38+
will be automatically started again. This is primarily useful for
39+
stopping instances.`
40+
)
41+
.optional(),
42+
notes: z.string()
43+
.describe("Open-ended text in markdown about this item.")
44+
.optional(),
45+
})
46+
.describe(
47+
"Create a new compute server with the provided configuration."
48+
);
49+
50+
export const CreateServerOutputSchema = z.union([
51+
FailedAPIOperationSchema,
52+
ComputeServerIdBodySchema.describe("The id of the created compute server."),
53+
]);
54+
55+
export type CreateServerInput = z.infer<typeof CreateServerInputSchema>;
56+
export type CreateServerOutput = z.infer<typeof CreateServerOutputSchema>;

‎src/packages/next/lib/api/schema/compute/delete-api-key.ts

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { z } from "../../framework";
2+
3+
import { FailedAPIOperationSchema, SuccessfulAPIOperationSchema } from "../common";
4+
5+
import { ComputeServerIdBodySchema } from "./common";
6+
7+
// OpenAPI spec
8+
//
9+
export const DeleteComputeServerAPIKeyInputSchema = z
10+
.object({
11+
id: ComputeServerIdBodySchema,
12+
})
13+
.describe(
14+
"Deletes the project API key associated with a particular compute server."
15+
);
16+
17+
export const DeleteComputeServerAPIKeyOutputSchema = z.union([
18+
FailedAPIOperationSchema,
19+
SuccessfulAPIOperationSchema,
20+
]);
21+
22+
export type DeleteComputeServerAPIKeyInput = z.infer<typeof DeleteComputeServerAPIKeyInputSchema>;
23+
export type DeleteComputeServerAPIKeyOutput = z.infer<typeof DeleteComputeServerAPIKeyOutputSchema>;

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { z } from "../../framework";
2+
3+
import { FailedAPIOperationSchema, SuccessfulAPIOperationSchema } from "../common";
4+
5+
import { ComputeServerIdBodySchema } from "./common";
6+
7+
// OpenAPI spec
8+
//
9+
export const DeleteComputeServerInputSchema = z
10+
.object({
11+
id: ComputeServerIdBodySchema,
12+
})
13+
.describe(
14+
"Deletes and deprovisions a compute server."
15+
);
16+
17+
export const DeleteComputeServerOutputSchema = z.union([
18+
FailedAPIOperationSchema,
19+
SuccessfulAPIOperationSchema,
20+
]);
21+
22+
export type DeleteComputeServerInput = z.infer<typeof DeleteComputeServerInputSchema>;
23+
export type DeleteComputeServerOutput = z.infer<typeof DeleteComputeServerOutputSchema>;

0 commit comments

Comments
 (0)