Sign in

pulls/pr_01m47d24b0e6n91zwymwxg0vpx

public

pr_01m47d24b0e6n91zwymwxg0vpx/packages/contracts/src/deployments.ts

219 lines8,575 bytesCodeBlame
1import type { User, Viewer } from "./identity";
2import type { Result } from "./result";
3
4/**
5 * Deployments: a project's production, deployed from its default branch on
6 * every push, and a live preview of every branch with an open pull request.
7 * Apps run as Workers in a Workers for Platforms namespace, so an app no
8 * one visits costs nothing. A paid feature: the workspace turns it on with
9 * a monthly plan (see `Feature` in `./billing`), and each project then
10 * chooses for itself.
11 */
12
13/** The domain apps are served on. Never g1t.sh, so they share no cookies with it. */
14export const DEPLOYMENTS_DOMAIN = "g1t.page";
15
16/** A project, as deployments name it. */
17export type ProjectRef = { workspace: string; slug: string };
18
19/** A project's deployment settings. */
20export type DeploySettings = {
21 /** Whether this project deploys at all. Off until someone turns it on. */
22 enabled: boolean;
23 /** A preview for every branch with an open pull request. */
24 previews: boolean;
25 /** The default branch deployed to production on every push. */
26 production: boolean;
27 /** Runs instead of the project's own `build` script. */
28 buildCommand: string | null;
29 /** What to serve, for a static site; found by itself when null. */
30 outputDir: string | null;
31 /** A preview no one has visited in this many days is taken down. */
32 idleDays: number;
33 /** Where production is served. */
34 productionUrl: string;
35 /**
36 * The project's own domain for production, once it is active: the first
37 * custom domain added that serves the app rather than redirecting. Null
38 * until one is.
39 */
40 primaryDomain: string | null;
41 /**
42 * What the last finished build found the project to be: a Workers
43 * project (it has a Workers config), a static site its build wrote, or
44 * plain HTML served as it is. Null until a build has finished. Read-only.
45 */
46 detected: DetectedKind | null;
47};
48
49export type DetectedKind = "workers" | "static" | "html";
50
51export type DeployKind = "preview" | "production";
52
53export type DeployStatus =
54 /** Waiting for a sandbox. */
55 | "queued"
56 | "building"
57 /** What its app serves now. */
58 | "ready"
59 /** Built and served, until a newer build of the same app replaced it. */
60 | "replaced"
61 /** Built and served, until its app was taken down. */
62 | "down"
63 | "failed"
64 /** Not built: the workspace's plan is off, or the build was replaced. */
65 | "skipped";
66
67/** One build of one commit, and where it went. */
68export type Deployment = {
69 id: string;
70 kind: DeployKind;
71 /** For a preview: the branch, or `pr-<n>` for a pull request from a fork. */
72 branch: string | null;
73 /** For a preview: its pull request. */
74 number: number | null;
75 commit: string;
76 status: DeployStatus;
77 url: string;
78 /** Why it failed or was skipped. */
79 error: string | null;
80 /** What the build could not provide, such as bindings not provisioned yet. */
81 warnings: string[];
82 /** How long the build ran, in seconds; charged at the container price. */
83 buildSeconds: number | null;
84 createdBy: string;
85 /** RFC 3339. */
86 createdAt: string;
87 finishedAt: string | null;
88};
89
90/** An app that is up: production, or one branch's preview. */
91export type LiveApp = {
92 kind: DeployKind;
93 branch: string | null;
94 number: number | null;
95 url: string;
96 commit: string;
97 /** RFC 3339: when it was last deployed. */
98 deployedAt: string;
99};
100
101/** One project at a glance, for the workspace's page. */
102export type ProjectDeploys = {
103 slug: string;
104 enabled: boolean;
105 production: LiveApp | null;
106 previews: number;
107 /** The newest build, whatever its status. */
108 latest: Deployment | null;
109};
110
111/** What a workspace's apps used this month against its plan. */
112export type DeployUsage = {
113 /** `YYYY-MM`. */
114 month: string;
115 requests: number;
116 cpuMs: number;
117 /** Apps up now, and the most at once this month. */
118 apps: number;
119 peakApps: number;
120 buildSeconds: number;
121 /** Charged so far this month for builds, in millionths of a dollar. */
122 buildMicros: number;
123 /** RFC 3339: when requests and CPU time were last counted. */
124 countedAt: string | null;
125};
126
127/** Where custom domains point: a hostname on g1t.page that routes to the dispatcher. */
128export const CUSTOM_DOMAIN_TARGET = "domains.g1t.page";
129
130/**
131 * A custom domain's state: `pending` until its DNS points at g1t (or its
132 * ownership record is found), `verifying` while its certificate is
133 * issued, then `active`. `failed` says why in `error`; `removing` is on
134 * its way out.
135 */
136export type DomainStatus = "pending" | "verifying" | "active" | "failed" | "removing";
137
138/** A DNS record the domain's owner adds at their DNS provider. */
139export type DomainRecord = {
140 /** `ALIAS` stands for a flattened CNAME at the apex, whatever the provider calls it. */
141 type: "CNAME" | "TXT" | "ALIAS";
142 /** The record's full name. */
143 name: string;
144 value: string;
145 /** What it is for, in a few words. */
146 purpose: string;
147};
148
149/** A hostname of the project's own, serving its production. */
150export type Domain = {
151 id: string;
152 hostname: string;
153 /** What it serves: `production`. */
154 target: "production";
155 status: DomainStatus;
156 /** Cloudflare's state for its certificate, as given. */
157 sslStatus: string | null;
158 /** Whether it is a registrable domain itself (`example.com`), which needs a flattened CNAME. */
159 apex: boolean;
160 /** Every record to add: where traffic goes, then any Cloudflare asks for. */
161 records: DomainRecord[];
162 /** A hostname this one redirects to (308, path and query kept), for a www/apex pair. */
163 redirectTo: string | null;
164 /** Why it is not active yet, or failed. */
165 error: string | null;
166 createdBy: string;
167 createdAt: string;
168 verifiedAt: string | null;
169};
170
171export type ProjectDomains = {
172 domains: Domain[];
173 /** The hostname every domain points at. */
174 target: string;
175 /** False until custom domains are switched on for g1t.page; `notice` says so. */
176 available: boolean;
177 notice: string | null;
178 /** Custom domains the Deployments plan includes, across the workspace; more are charged by the month. */
179 included: number;
180 /** The workspace's custom domains now. */
181 used: number;
182};
183
184export interface DeploymentsApi {
185 /** Members of the workspace only. */
186 settings(project: ProjectRef, viewer: Viewer): Promise<Result<DeploySettings>>;
187 /** Members only. Turning deployments on needs the workspace's plan. */
188 updateSettings(actor: User, project: ProjectRef, changes: Partial<DeploySettings>): Promise<Result<DeploySettings>>;
189 /** The newest builds first, and what is up now. Members only. */
190 list(project: ProjectRef, viewer: Viewer): Promise<Result<{ deployments: Deployment[]; live: LiveApp[] }>>;
191 /** One build, with its log. Members only. */
192 get(project: ProjectRef, id: string, viewer: Viewer): Promise<Result<Deployment & { log: string | null }>>;
193 /** Builds production (`branch` null), or a branch's preview, again from its head. */
194 redeploy(actor: User, project: ProjectRef, branch: string | null): Promise<Result<Deployment>>;
195 /**
196 * Builds previews of the projects that use this one, under the same
197 * branch, each pointed at this branch's preview. Answers at once with the
198 * names of the projects being built; the builds go on in the
199 * background. Members only.
200 */
201 stack(actor: User, project: ProjectRef, branch: string): Promise<Result<string[]>>;
202 /** Takes production (`branch` null), or a branch's preview, down now. */
203 takeDown(actor: User, project: ProjectRef, branch: string | null): Promise<Result<true>>;
204 /** Every project of a workspace at a glance. Members only. */
205 overview(workspace: string, viewer: Viewer): Promise<Result<ProjectDeploys[]>>;
206 /** What the workspace's apps used this month. Members only. */
207 usage(workspace: string, viewer: Viewer): Promise<Result<DeployUsage>>;
208 /** The project's custom domains. Members only. */
209 domains(project: ProjectRef, viewer: Viewer): Promise<Result<ProjectDomains>>;
210 /**
211 * Adds a custom domain for production. With `twin`, its www or apex twin
212 * is added too, redirecting to it. Members only; needs the Deployments plan.
213 */
214 addDomain(actor: User, project: ProjectRef, hostname: string, options?: { twin?: boolean }): Promise<Result<Domain[]>>;
215 /** Removes a custom domain, and any domain redirecting to it. Members only. */
216 removeDomain(actor: User, project: ProjectRef, id: string): Promise<Result<true>>;
217 /** Asks Cloudflare to check the domain again now. Members only. */
218 refreshDomain(actor: User, project: ProjectRef, id: string): Promise<Result<Domain>>;
219}