@niwa-labs/forge 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +52 -2
- package/package.json +30 -4
- package/src/actions.ts +389 -0
- package/src/cockpit/actions.ts +94 -0
- package/src/cockpit/index.tsx +19 -0
- package/src/cockpit/page.tsx +158 -0
- package/src/cockpit/pulls.ts +103 -0
- package/src/flow.ts +232 -0
- package/src/gitlab.ts +263 -0
- package/src/index.ts +765 -0
- package/src/merge.ts +309 -0
- package/src/normalize.ts +186 -0
- package/src/observe.ts +464 -0
- package/src/prs.ts +122 -0
- package/src/queries.ts +152 -0
- package/src/record-types.ts +353 -0
- package/src/records.ts +8 -0
- package/src/secrets.ts +40 -0
- package/src/servers.ts +121 -0
- package/src/targets.ts +82 -0
- package/src/workflows/push-reaction.ts +59 -0
- package/test/actions.test.ts +235 -0
- package/test/cockpit-actions.test.ts +55 -0
- package/test/cockpit-pulls.test.ts +58 -0
- package/test/fake-gitlab.ts +452 -0
- package/test/flow.test.ts +239 -0
- package/test/gitlab.test.ts +91 -0
- package/test/merge.test.ts +251 -0
- package/test/observe.test.ts +454 -0
- package/test/prs.test.ts +125 -0
- package/test/push-reaction.test.ts +92 -0
- package/test/queries.test.ts +144 -0
- package/test/script-surface.test.ts +185 -0
- package/test/support.ts +109 -0
- package/test/targets.test.ts +42 -0
- package/tsconfig.json +15 -0
package/src/gitlab.ts
ADDED
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The REST API of a GitLab server, as the module speaks to it.
|
|
3
|
+
*
|
|
4
|
+
* `fetch` is given, so a test speaks to a fake server and nothing here reaches the network by
|
|
5
|
+
* itself. A read keeps the ETag of every URL it read, page by page, and asks again with
|
|
6
|
+
* `If-None-Match`: a `304` answers what was read before. The server's own counts of the limit are
|
|
7
|
+
* what the client goes by: when `RateLimit-Remaining` reaches zero it does not ask again before
|
|
8
|
+
* `RateLimit-Reset`, and a `429` is refused for its `Retry-After`. The token goes in a header and
|
|
9
|
+
* nowhere else: no error says it.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { CatchableError } from "@niwa-labs/core";
|
|
13
|
+
|
|
14
|
+
/** What the client fetches with: the global `fetch`, or a fake server. */
|
|
15
|
+
export type FetchLike = (url: string, init: { method: string; headers: Record<string, string>; body?: string }) => Promise<Response>;
|
|
16
|
+
|
|
17
|
+
/** Why a call to the server did not do what it was asked. */
|
|
18
|
+
export type ForgeErrorCode =
|
|
19
|
+
| "unknown-server"
|
|
20
|
+
| "unknown-secret"
|
|
21
|
+
| "unsafe-secret"
|
|
22
|
+
| "unauthorized"
|
|
23
|
+
| "forbidden"
|
|
24
|
+
| "not-found"
|
|
25
|
+
| "conflict"
|
|
26
|
+
| "refused"
|
|
27
|
+
| "rate-limited"
|
|
28
|
+
| "server"
|
|
29
|
+
| "not-watched"
|
|
30
|
+
| "merged"
|
|
31
|
+
| "wrong-ref";
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* A refusal of the forge module or of the server: the code says which, the message says why. It is
|
|
35
|
+
* the caller's to catch: a pull request that is gone or a limit that is spent is an answer.
|
|
36
|
+
*/
|
|
37
|
+
export class ForgeError extends CatchableError {
|
|
38
|
+
override name = "ForgeError";
|
|
39
|
+
override readonly code: ForgeErrorCode;
|
|
40
|
+
/** The HTTP status of the server's answer, when the server answered. */
|
|
41
|
+
readonly status: number | undefined;
|
|
42
|
+
/** For `rate-limited`: how long to wait before asking again. */
|
|
43
|
+
readonly retryAfterMs: number | undefined;
|
|
44
|
+
|
|
45
|
+
constructor(code: ForgeErrorCode, message: string, opts: { status?: number; retryAfterMs?: number } = {}) {
|
|
46
|
+
super(message);
|
|
47
|
+
this.code = code;
|
|
48
|
+
this.status = opts.status;
|
|
49
|
+
this.retryAfterMs = opts.retryAfterMs;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export interface GitLabOptions {
|
|
54
|
+
/** The base URL of the server, such as `https://gitlab.example.com`. */
|
|
55
|
+
readonly url: string;
|
|
56
|
+
/** The token, read when a request is made: the owner may replace it while the host runs. */
|
|
57
|
+
readonly token: () => string;
|
|
58
|
+
readonly fetch: FetchLike;
|
|
59
|
+
/** The clock, in milliseconds since the epoch. */
|
|
60
|
+
readonly now: () => number;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** A query string, from values that are set. */
|
|
64
|
+
export type Query = Record<string, string | number | boolean | undefined>;
|
|
65
|
+
|
|
66
|
+
/** What was read from a URL, and the tag that names it. */
|
|
67
|
+
interface Cached {
|
|
68
|
+
readonly etag: string;
|
|
69
|
+
readonly body: unknown;
|
|
70
|
+
readonly next: string | undefined;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The most pages a list reads: past it the list is cut, rather than read for ever. */
|
|
74
|
+
const MAX_PAGES = 20;
|
|
75
|
+
|
|
76
|
+
/** A client of one GitLab server. */
|
|
77
|
+
export class GitLab {
|
|
78
|
+
readonly #options: GitLabOptions;
|
|
79
|
+
readonly #cache = new Map<string, Cached>();
|
|
80
|
+
/** The moment before which the server is not asked again; 0 when nothing holds it back. */
|
|
81
|
+
#blockedUntil = 0;
|
|
82
|
+
|
|
83
|
+
constructor(options: GitLabOptions) {
|
|
84
|
+
this.#options = options;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** How long until the server may be asked again, in milliseconds; 0 when it may be now. */
|
|
88
|
+
waitMs(): number {
|
|
89
|
+
return Math.max(0, this.#blockedUntil - this.#options.now());
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Read one resource. */
|
|
93
|
+
async get<T>(path: string, query: Query = {}): Promise<T> {
|
|
94
|
+
return (await this.#read(this.#url(path, { ...query }))).body as T;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Read every page of a list, up to a bound. With `enough`, the reading stops after the first page
|
|
99
|
+
* of which it says the rest is not needed.
|
|
100
|
+
*/
|
|
101
|
+
async list<T>(path: string, query: Query = {}, enough?: (page: readonly T[]) => boolean): Promise<T[]> {
|
|
102
|
+
return (await this.pages<T>(path, query, enough === undefined ? {} : { enough })).items;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The same, with the bound given, and the answer says whether the list was cut by it: `truncated`
|
|
107
|
+
* is true when the server had a page more that was not read and `enough` had not asked to stop.
|
|
108
|
+
*/
|
|
109
|
+
async pages<T>(path: string, query: Query = {}, opts: { enough?: (page: readonly T[]) => boolean; maxPages?: number } = {}): Promise<{ items: T[]; truncated: boolean }> {
|
|
110
|
+
const items: T[] = [];
|
|
111
|
+
const bound = opts.maxPages ?? MAX_PAGES;
|
|
112
|
+
let page: string | undefined = "1";
|
|
113
|
+
for (let read = 0; page !== undefined; read += 1) {
|
|
114
|
+
if (read >= bound) return { items, truncated: true };
|
|
115
|
+
const answer: Cached = await this.#read(this.#url(path, { per_page: 100, ...query, page }));
|
|
116
|
+
const got = answer.body as T[];
|
|
117
|
+
items.push(...got);
|
|
118
|
+
if (opts.enough?.(got) === true) break;
|
|
119
|
+
page = answer.next;
|
|
120
|
+
}
|
|
121
|
+
return { items, truncated: false };
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Read the end of a resource that may be large, such as the log of a job: the last `keep` bytes
|
|
126
|
+
* and how many bytes the whole was. The body is streamed and only the tail is held; it is decoded
|
|
127
|
+
* after it is chosen, from the first whole character.
|
|
128
|
+
*/
|
|
129
|
+
async tail(path: string, keep: number): Promise<{ text: string; size: number }> {
|
|
130
|
+
const response = await this.#fetch("GET", this.#url(path, {}), {});
|
|
131
|
+
const chunks: Uint8Array[] = [];
|
|
132
|
+
let held = 0;
|
|
133
|
+
let size = 0;
|
|
134
|
+
const reader = response.body?.getReader();
|
|
135
|
+
for (let chunk = await reader?.read(); chunk !== undefined && !chunk.done; chunk = await reader?.read()) {
|
|
136
|
+
chunks.push(chunk.value);
|
|
137
|
+
held += chunk.value.length;
|
|
138
|
+
size += chunk.value.length;
|
|
139
|
+
// The oldest chunk goes once the ones after it hold the tail.
|
|
140
|
+
while (chunks.length > 1 && held - (chunks[0]?.length ?? 0) >= keep) held -= chunks.shift()?.length ?? 0;
|
|
141
|
+
}
|
|
142
|
+
const bytes = new Uint8Array(held);
|
|
143
|
+
let at = 0;
|
|
144
|
+
for (const chunk of chunks) {
|
|
145
|
+
bytes.set(chunk, at);
|
|
146
|
+
at += chunk.length;
|
|
147
|
+
}
|
|
148
|
+
let start = Math.max(0, held - keep);
|
|
149
|
+
// A cut inside a character leaves its continuation bytes: start after them.
|
|
150
|
+
while (start > 0 && start < held && ((bytes[start] ?? 0) & 0xc0) === 0x80) start += 1;
|
|
151
|
+
return { text: new TextDecoder().decode(bytes.subarray(start)), size };
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Change something: `POST`, `PUT` or `DELETE`, with a JSON body. `secrets` are values the body
|
|
156
|
+
* carries that no error may repeat: a server may echo what it was given.
|
|
157
|
+
*/
|
|
158
|
+
async send<T>(method: "POST" | "PUT" | "DELETE", path: string, body?: unknown, secrets: readonly string[] = []): Promise<T> {
|
|
159
|
+
const response = await this.#fetch(method, this.#url(path, {}), body === undefined ? {} : { "Content-Type": "application/json" }, body, secrets);
|
|
160
|
+
if (response.status === 204) return undefined as T;
|
|
161
|
+
const text = await response.text();
|
|
162
|
+
return (text.length === 0 ? undefined : JSON.parse(text)) as T;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
#url(path: string, query: Query): string {
|
|
166
|
+
const url = new URL(`${this.#options.url.replace(/\/+$/, "")}/api/v4${path}`);
|
|
167
|
+
for (const [key, value] of Object.entries(query)) if (value !== undefined) url.searchParams.set(key, String(value));
|
|
168
|
+
return url.toString();
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
async #read(url: string): Promise<Cached> {
|
|
172
|
+
const cached = this.#cache.get(url);
|
|
173
|
+
const response = await this.#fetch("GET", url, cached === undefined ? {} : { "If-None-Match": cached.etag });
|
|
174
|
+
if (response.status === 304 && cached !== undefined) return cached;
|
|
175
|
+
const body: unknown = await response.json();
|
|
176
|
+
const next = response.headers.get("X-Next-Page") ?? "";
|
|
177
|
+
const answer: Cached = { etag: response.headers.get("ETag") ?? "", body, next: next.length > 0 ? next : undefined };
|
|
178
|
+
if (answer.etag.length > 0) this.#cache.set(url, answer);
|
|
179
|
+
else this.#cache.delete(url);
|
|
180
|
+
return answer;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
async #fetch(method: string, url: string, headers: Record<string, string>, body?: unknown, secrets: readonly string[] = []): Promise<Response> {
|
|
184
|
+
const wait = this.waitMs();
|
|
185
|
+
if (wait > 0) {
|
|
186
|
+
throw new ForgeError("rate-limited", `the server's request limit is spent; it may be asked again in ${String(Math.ceil(wait / 1000))}s`, {
|
|
187
|
+
retryAfterMs: wait,
|
|
188
|
+
});
|
|
189
|
+
}
|
|
190
|
+
const token = this.#options.token();
|
|
191
|
+
const init = {
|
|
192
|
+
method,
|
|
193
|
+
headers: { Accept: "application/json", ...headers, "PRIVATE-TOKEN": token },
|
|
194
|
+
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
|
195
|
+
};
|
|
196
|
+
let response: Response;
|
|
197
|
+
try {
|
|
198
|
+
response = await this.#options.fetch(url, init);
|
|
199
|
+
} catch (error) {
|
|
200
|
+
throw new ForgeError("server", `${method} ${pathOf(url)} did not reach the server: ${error instanceof Error ? error.name : "error"}`);
|
|
201
|
+
}
|
|
202
|
+
this.#note(response);
|
|
203
|
+
if (response.ok || response.status === 304) return response;
|
|
204
|
+
throw await errorOf(method, url, response, this.waitMs(), [token, ...secrets]);
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** Take the server's counts of its limit. */
|
|
208
|
+
#note(response: Response): void {
|
|
209
|
+
const now = this.#options.now();
|
|
210
|
+
if (response.status === 429) {
|
|
211
|
+
this.#blockedUntil = Math.max(this.#blockedUntil, now + retryAfterMs(response.headers.get("Retry-After"), now));
|
|
212
|
+
return;
|
|
213
|
+
}
|
|
214
|
+
const remaining = Number(response.headers.get("RateLimit-Remaining") ?? Number.NaN);
|
|
215
|
+
const reset = Number(response.headers.get("RateLimit-Reset") ?? Number.NaN);
|
|
216
|
+
if (remaining === 0 && Number.isFinite(reset)) this.#blockedUntil = Math.max(this.#blockedUntil, reset * 1000);
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** `Retry-After` in milliseconds: seconds or an HTTP date; a minute when the server does not say. */
|
|
221
|
+
function retryAfterMs(header: string | null, now: number): number {
|
|
222
|
+
if (header === null) return 60_000;
|
|
223
|
+
const seconds = Number(header);
|
|
224
|
+
if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
|
|
225
|
+
const at = Date.parse(header);
|
|
226
|
+
return Number.isFinite(at) ? Math.max(0, at - now) : 60_000;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** The path of a URL, for a message: never its query, never a header. */
|
|
230
|
+
function pathOf(url: string): string {
|
|
231
|
+
return new URL(url).pathname;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/** The error a failed answer stands for, with what the server said. */
|
|
235
|
+
async function errorOf(method: string, url: string, response: Response, waitMs: number, secrets: readonly string[]): Promise<ForgeError> {
|
|
236
|
+
const said = await messageOf(response, secrets);
|
|
237
|
+
const what = `${method} ${pathOf(url)}: ${String(response.status)}${said === undefined ? "" : ` ${said}`}`;
|
|
238
|
+
const status = response.status;
|
|
239
|
+
if (status === 429) return new ForgeError("rate-limited", what, { status, retryAfterMs: waitMs });
|
|
240
|
+
if (status === 401) return new ForgeError("unauthorized", what, { status });
|
|
241
|
+
if (status === 403) return new ForgeError("forbidden", what, { status });
|
|
242
|
+
if (status === 404) return new ForgeError("not-found", what, { status });
|
|
243
|
+
if (status === 409) return new ForgeError("conflict", what, { status });
|
|
244
|
+
if (status >= 400 && status < 500) return new ForgeError("refused", what, { status });
|
|
245
|
+
return new ForgeError("server", what, { status });
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* The `message` or `error` of an answer, as text, bounded. The secrets are taken out of the whole
|
|
250
|
+
* text first: cut before, one that straddles the bound would leave its first characters in.
|
|
251
|
+
*/
|
|
252
|
+
async function messageOf(response: Response, secrets: readonly string[]): Promise<string | undefined> {
|
|
253
|
+
try {
|
|
254
|
+
const body = (await response.json()) as { message?: unknown; error?: unknown };
|
|
255
|
+
const said = body.message ?? body.error;
|
|
256
|
+
if (said === undefined) return undefined;
|
|
257
|
+
let text = typeof said === "string" ? said : JSON.stringify(said);
|
|
258
|
+
for (const value of secrets) if (value.length > 0) text = text.split(value).join("[secret]");
|
|
259
|
+
return text.slice(0, 500);
|
|
260
|
+
} catch {
|
|
261
|
+
return undefined;
|
|
262
|
+
}
|
|
263
|
+
}
|