@fabrika/github-app 0.8.1 → 0.9.0-dev.1
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/package.json +1 -1
- package/src/errors.ts +10 -2
- package/src/index.ts +8 -1
- package/src/repository-types.ts +56 -2
- package/src/repository-validation.ts +40 -1
- package/src/repository.ts +88 -8
package/package.json
CHANGED
package/src/errors.ts
CHANGED
|
@@ -2,8 +2,16 @@ export function configurationError(): Error {
|
|
|
2
2
|
return new Error('GitHub App configuration is invalid')
|
|
3
3
|
}
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
/** GitHub answered a request with an unexpected status; the message never carries GitHub's response text. */
|
|
6
|
+
export class GitHubRequestError extends Error {
|
|
7
|
+
constructor(readonly status: number) {
|
|
8
|
+
super(`GitHub App request failed with status ${status}`)
|
|
9
|
+
this.name = 'GitHubRequestError'
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export function requestStatusError(status: number): GitHubRequestError {
|
|
14
|
+
return new GitHubRequestError(status)
|
|
7
15
|
}
|
|
8
16
|
|
|
9
17
|
export function responseError(): Error {
|
package/src/index.ts
CHANGED
|
@@ -1,9 +1,14 @@
|
|
|
1
1
|
export { GitHubAppClient } from './client'
|
|
2
|
-
export { GitHubBranchConflictError, GitHubNotFoundError, GitHubStaleHeadError } from './errors'
|
|
2
|
+
export { GitHubBranchConflictError, GitHubNotFoundError, GitHubRequestError, GitHubStaleHeadError } from './errors'
|
|
3
3
|
export { buildGitHubAppManifest, exchangeGitHubAppManifestCode } from './manifest'
|
|
4
4
|
export type {
|
|
5
|
+
GitHubBlobRead,
|
|
6
|
+
GitHubBlobRef,
|
|
7
|
+
GitHubChangedFile,
|
|
8
|
+
GitHubChangedFileStatus,
|
|
5
9
|
GitHubCommit,
|
|
6
10
|
GitHubCommitFilesInput,
|
|
11
|
+
GitHubComparison,
|
|
7
12
|
GitHubCreateBranchInput,
|
|
8
13
|
GitHubFileChange,
|
|
9
14
|
GitHubFileRead,
|
|
@@ -15,6 +20,8 @@ export type {
|
|
|
15
20
|
GitHubTextFile,
|
|
16
21
|
GitHubTreeEntry,
|
|
17
22
|
GitHubTreeListing,
|
|
23
|
+
GitHubUnreadablePath,
|
|
24
|
+
GitHubUnreadableReason,
|
|
18
25
|
} from './repository-types'
|
|
19
26
|
export { pemToPkcs8 } from './signing'
|
|
20
27
|
export type {
|
package/src/repository-types.ts
CHANGED
|
@@ -32,11 +32,59 @@ export interface GitHubTextFile {
|
|
|
32
32
|
readonly content: string
|
|
33
33
|
}
|
|
34
34
|
|
|
35
|
+
/**
|
|
36
|
+
* Why a requested path was not read: `missing` (no such path), `not_a_file` (a directory, symlink or submodule),
|
|
37
|
+
* `too_large` (over the per-file bound), `binary` (not UTF-8), `budget` (past the read's total byte bound).
|
|
38
|
+
*/
|
|
39
|
+
export type GitHubUnreadableReason = 'missing' | 'not_a_file' | 'too_large' | 'binary' | 'budget'
|
|
40
|
+
|
|
41
|
+
export interface GitHubUnreadablePath {
|
|
42
|
+
readonly path: string
|
|
43
|
+
readonly reason: GitHubUnreadableReason
|
|
44
|
+
}
|
|
45
|
+
|
|
35
46
|
export interface GitHubFileRead {
|
|
36
47
|
readonly commitSha: string
|
|
37
48
|
readonly files: readonly GitHubTextFile[]
|
|
38
|
-
/** Requested paths that
|
|
39
|
-
readonly
|
|
49
|
+
/** Requested paths that were not read at `commitSha`, in request order. */
|
|
50
|
+
readonly unreadable: readonly GitHubUnreadablePath[]
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** A blob named by a tree listing of the same repository. */
|
|
54
|
+
export interface GitHubBlobRef {
|
|
55
|
+
readonly path: string
|
|
56
|
+
readonly sha: string
|
|
57
|
+
readonly size: number
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export interface GitHubBlobRead {
|
|
61
|
+
readonly files: readonly GitHubTextFile[]
|
|
62
|
+
/** Blobs that were not read (`too_large`, `budget` or `binary`), in request order. */
|
|
63
|
+
readonly unreadable: readonly GitHubUnreadablePath[]
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export type GitHubChangedFileStatus = 'added' | 'removed' | 'modified' | 'renamed' | 'copied' | 'changed' | 'unchanged'
|
|
67
|
+
|
|
68
|
+
export interface GitHubChangedFile {
|
|
69
|
+
readonly path: string
|
|
70
|
+
/** The path before a rename or copy. */
|
|
71
|
+
readonly previousPath: string | null
|
|
72
|
+
readonly status: GitHubChangedFileStatus
|
|
73
|
+
readonly additions: number
|
|
74
|
+
readonly deletions: number
|
|
75
|
+
/** The unified diff hunk; null when GitHub omits it (a binary file or a very large change). */
|
|
76
|
+
readonly patch: string | null
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export interface GitHubComparison {
|
|
80
|
+
readonly baseSha: string
|
|
81
|
+
readonly headSha: string
|
|
82
|
+
/** Commits on head that are not on base. */
|
|
83
|
+
readonly aheadBy: number
|
|
84
|
+
readonly behindBy: number
|
|
85
|
+
readonly files: readonly GitHubChangedFile[]
|
|
86
|
+
/** GitHub lists at most 300 files of a comparison; true when it listed that many, so more may have changed. */
|
|
87
|
+
readonly filesCapped: boolean
|
|
40
88
|
}
|
|
41
89
|
|
|
42
90
|
export interface GitHubFileChange {
|
|
@@ -84,8 +132,14 @@ export interface GitHubRepositoryClient {
|
|
|
84
132
|
readRef(branch: string, signal?: AbortSignal): Promise<GitHubRef | null>
|
|
85
133
|
readTree(commitSha: string, directory?: string, signal?: AbortSignal): Promise<GitHubTreeListing>
|
|
86
134
|
readFiles(commitSha: string, paths: readonly string[], signal?: AbortSignal): Promise<GitHubFileRead>
|
|
135
|
+
/** Reads listed blobs as text without walking the tree again, within the same per-file and total bounds as `readFiles`. */
|
|
136
|
+
readBlobTexts(blobs: readonly GitHubBlobRef[], signal?: AbortSignal): Promise<GitHubBlobRead>
|
|
137
|
+
/** The changes from the merge base of `baseSha` and `headSha` to `headSha`. */
|
|
138
|
+
compareCommits(baseSha: string, headSha: string, signal?: AbortSignal): Promise<GitHubComparison>
|
|
87
139
|
/** Idempotent: an existing branch already at `fromSha` is returned; one elsewhere is a conflict. */
|
|
88
140
|
createBranch(input: GitHubCreateBranchInput): Promise<GitHubRef>
|
|
141
|
+
/** Idempotent: `deleted` is false when the branch did not exist. GitHub closes an open pull request from it. */
|
|
142
|
+
deleteBranch(branch: string, signal?: AbortSignal): Promise<{ readonly deleted: boolean }>
|
|
89
143
|
/** Creates exactly one commit on top of `expectedHeadSha` and moves the branch to it without force. */
|
|
90
144
|
commitFiles(input: GitHubCommitFilesInput): Promise<GitHubCommit>
|
|
91
145
|
openPullRequest(input: GitHubOpenPullRequestInput): Promise<GitHubPullRequestRef>
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { z } from 'zod'
|
|
2
2
|
import { configurationError, responseError } from './errors'
|
|
3
|
-
import type { GitHubCommit, GitHubPullRequestRef, GitHubRef, GitHubTreeEntry } from './repository-types'
|
|
3
|
+
import type { GitHubCommit, GitHubComparison, GitHubPullRequestRef, GitHubRef, GitHubTreeEntry } from './repository-types'
|
|
4
4
|
import { hasAsciiControl } from './validation'
|
|
5
5
|
|
|
6
6
|
export const MAX_TREE_ENTRIES = 5000
|
|
@@ -20,6 +20,10 @@ export const MAX_PULL_REQUEST_RESPONSE_BYTES = 1024 * 1024
|
|
|
20
20
|
// A commit echoes its message, which existing history does not bound.
|
|
21
21
|
export const MAX_COMMIT_RESPONSE_BYTES = 1024 * 1024
|
|
22
22
|
export const MAX_PATH_SEGMENTS = 64
|
|
23
|
+
/** GitHub's own bound on the files of one comparison. */
|
|
24
|
+
export const MAX_COMPARE_FILES = 300
|
|
25
|
+
// Each file of a comparison carries its patch.
|
|
26
|
+
export const MAX_COMPARE_RESPONSE_BYTES = 8 * 1024 * 1024
|
|
23
27
|
|
|
24
28
|
const SHA_PATTERN = /^[a-f0-9]{40}$/
|
|
25
29
|
const LONE_SURROGATE_PATTERN = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/
|
|
@@ -137,6 +141,41 @@ export function decodeTextBlob(body: unknown, expectedSha: string, expectedSize:
|
|
|
137
141
|
}
|
|
138
142
|
}
|
|
139
143
|
|
|
144
|
+
const comparisonSchema = z.object({
|
|
145
|
+
ahead_by: z.number().int().nonnegative(),
|
|
146
|
+
behind_by: z.number().int().nonnegative(),
|
|
147
|
+
merge_base_commit: z.object({ sha: shaSchema }),
|
|
148
|
+
files: z.array(z.object({
|
|
149
|
+
filename: z.string(),
|
|
150
|
+
previous_filename: z.string().optional(),
|
|
151
|
+
status: z.enum(['added', 'removed', 'modified', 'renamed', 'copied', 'changed', 'unchanged']),
|
|
152
|
+
additions: z.number().int().nonnegative(),
|
|
153
|
+
deletions: z.number().int().nonnegative(),
|
|
154
|
+
patch: z.string().optional(),
|
|
155
|
+
})).max(MAX_COMPARE_FILES).optional(),
|
|
156
|
+
})
|
|
157
|
+
|
|
158
|
+
export function decodeComparison(body: unknown, headSha: string): GitHubComparison {
|
|
159
|
+
const result = comparisonSchema.safeParse(body)
|
|
160
|
+
if (!result.success) throw responseError()
|
|
161
|
+
const files = (result.data.files ?? []).map((file) => ({
|
|
162
|
+
path: file.filename,
|
|
163
|
+
previousPath: file.previous_filename ?? null,
|
|
164
|
+
status: file.status,
|
|
165
|
+
additions: file.additions,
|
|
166
|
+
deletions: file.deletions,
|
|
167
|
+
patch: file.patch ?? null,
|
|
168
|
+
}))
|
|
169
|
+
return {
|
|
170
|
+
baseSha: result.data.merge_base_commit.sha,
|
|
171
|
+
headSha,
|
|
172
|
+
aheadBy: result.data.ahead_by,
|
|
173
|
+
behindBy: result.data.behind_by,
|
|
174
|
+
files,
|
|
175
|
+
filesCapped: files.length === MAX_COMPARE_FILES,
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
140
179
|
const pullRequestSchema = z.object({ number: z.number().int().positive(), html_url: z.string().url() })
|
|
141
180
|
|
|
142
181
|
export function decodePullRequest(body: unknown, created: boolean): GitHubPullRequestRef {
|
package/src/repository.ts
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
import { configurationError, GitHubBranchConflictError, GitHubNotFoundError, GitHubStaleHeadError, requestStatusError, responseError } from './errors'
|
|
2
2
|
import type {
|
|
3
|
+
GitHubBlobRead,
|
|
4
|
+
GitHubBlobRef,
|
|
3
5
|
GitHubCommit,
|
|
4
6
|
GitHubCommitFilesInput,
|
|
7
|
+
GitHubComparison,
|
|
5
8
|
GitHubCreateBranchInput,
|
|
6
9
|
GitHubFileRead,
|
|
7
10
|
GitHubOpenPullRequestInput,
|
|
@@ -11,9 +14,12 @@ import type {
|
|
|
11
14
|
GitHubTextFile,
|
|
12
15
|
GitHubTreeEntry,
|
|
13
16
|
GitHubTreeListing,
|
|
17
|
+
GitHubUnreadablePath,
|
|
18
|
+
GitHubUnreadableReason,
|
|
14
19
|
} from './repository-types'
|
|
15
20
|
import {
|
|
16
21
|
decodeCommit,
|
|
22
|
+
decodeComparison,
|
|
17
23
|
decodeCreatedTreeSha,
|
|
18
24
|
decodePullRequest,
|
|
19
25
|
decodePullRequestList,
|
|
@@ -26,6 +32,7 @@ import {
|
|
|
26
32
|
MAX_CHANGED_FILES,
|
|
27
33
|
MAX_COMMIT_MESSAGE_BYTES,
|
|
28
34
|
MAX_COMMIT_RESPONSE_BYTES,
|
|
35
|
+
MAX_COMPARE_RESPONSE_BYTES,
|
|
29
36
|
MAX_FILE_BYTES,
|
|
30
37
|
MAX_PULL_REQUEST_BODY_BYTES,
|
|
31
38
|
MAX_PULL_REQUEST_RESPONSE_BYTES,
|
|
@@ -54,10 +61,13 @@ export interface RepositoryClientConfig {
|
|
|
54
61
|
readonly timeoutMs: number
|
|
55
62
|
}
|
|
56
63
|
|
|
64
|
+
/** Blob reads in flight at once; enough to hide latency, few enough to stay clear of GitHub's secondary rate limits. */
|
|
65
|
+
const BLOB_READ_CONCURRENCY = 6
|
|
66
|
+
|
|
57
67
|
type RequestResult = { readonly ok: true; readonly body: unknown } | { readonly ok: false; readonly status: number }
|
|
58
68
|
|
|
59
69
|
interface RequestOptions {
|
|
60
|
-
readonly method?: 'GET' | 'POST' | 'PATCH'
|
|
70
|
+
readonly method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
|
|
61
71
|
readonly body?: unknown
|
|
62
72
|
readonly signal?: AbortSignal | undefined
|
|
63
73
|
readonly maxResponseBytes?: number
|
|
@@ -112,25 +122,74 @@ class RepositoryClient implements GitHubRepositoryClient {
|
|
|
112
122
|
for (const path of paths) validatePath(path)
|
|
113
123
|
const directories = this.#treeWalker((await this.#readCommit(commitSha, signal)).treeSha, signal)
|
|
114
124
|
const files: GitHubTextFile[] = []
|
|
115
|
-
const
|
|
125
|
+
const unreadable: GitHubUnreadablePath[] = []
|
|
116
126
|
let remainingBytes = MAX_READ_BYTES
|
|
117
127
|
for (const path of paths) {
|
|
118
|
-
const entry = await directories.find(path)
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
missingPaths.push(path)
|
|
128
|
+
const entry = readableBlob(await directories.find(path), remainingBytes)
|
|
129
|
+
if (typeof entry === 'string') {
|
|
130
|
+
unreadable.push({ path, reason: entry })
|
|
122
131
|
continue
|
|
123
132
|
}
|
|
124
133
|
const body = await this.#readGitObject(`/git/blobs/${entry.sha}`, signal, MAX_BLOB_RESPONSE_BYTES)
|
|
125
134
|
const content = decodeTextBlob(body, entry.sha, entry.size)
|
|
126
135
|
if (content === null) {
|
|
127
|
-
|
|
136
|
+
unreadable.push({ path, reason: 'binary' })
|
|
128
137
|
continue
|
|
129
138
|
}
|
|
130
139
|
remainingBytes -= entry.size
|
|
131
140
|
files.push({ path, content })
|
|
132
141
|
}
|
|
133
|
-
return { commitSha, files,
|
|
142
|
+
return { commitSha, files, unreadable }
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
async readBlobTexts(blobs: readonly GitHubBlobRef[], signal?: AbortSignal): Promise<GitHubBlobRead> {
|
|
146
|
+
if (blobs.length === 0 || blobs.length > MAX_READ_PATHS || new Set(blobs.map((blob) => blob.path)).size !== blobs.length) {
|
|
147
|
+
throw configurationError()
|
|
148
|
+
}
|
|
149
|
+
for (const blob of blobs) {
|
|
150
|
+
validatePath(blob.path)
|
|
151
|
+
validateSha(blob.sha)
|
|
152
|
+
if (!Number.isSafeInteger(blob.size) || blob.size < 0) throw configurationError()
|
|
153
|
+
}
|
|
154
|
+
const unreadable = new Map<string, GitHubUnreadableReason>()
|
|
155
|
+
const selected: GitHubBlobRef[] = []
|
|
156
|
+
let remainingBytes = MAX_READ_BYTES
|
|
157
|
+
for (const blob of blobs) {
|
|
158
|
+
if (blob.size > MAX_FILE_BYTES) unreadable.set(blob.path, 'too_large')
|
|
159
|
+
else if (blob.size > remainingBytes) unreadable.set(blob.path, 'budget')
|
|
160
|
+
else {
|
|
161
|
+
remainingBytes -= blob.size
|
|
162
|
+
selected.push(blob)
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
const contents = new Map<string, string>()
|
|
166
|
+
for (let start = 0; start < selected.length; start += BLOB_READ_CONCURRENCY) {
|
|
167
|
+
await Promise.all(
|
|
168
|
+
selected.slice(start, start + BLOB_READ_CONCURRENCY).map(async (blob) => {
|
|
169
|
+
const body = await this.#readGitObject(`/git/blobs/${blob.sha}`, signal, MAX_BLOB_RESPONSE_BYTES)
|
|
170
|
+
const content = decodeTextBlob(body, blob.sha, blob.size)
|
|
171
|
+
if (content === null) unreadable.set(blob.path, 'binary')
|
|
172
|
+
else contents.set(blob.path, content)
|
|
173
|
+
}),
|
|
174
|
+
)
|
|
175
|
+
}
|
|
176
|
+
const files: GitHubTextFile[] = []
|
|
177
|
+
const unread: GitHubUnreadablePath[] = []
|
|
178
|
+
for (const blob of blobs) {
|
|
179
|
+
const content = contents.get(blob.path)
|
|
180
|
+
const reason = unreadable.get(blob.path)
|
|
181
|
+
if (content !== undefined) files.push({ path: blob.path, content })
|
|
182
|
+
else if (reason !== undefined) unread.push({ path: blob.path, reason })
|
|
183
|
+
}
|
|
184
|
+
return { files, unreadable: unread }
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
async compareCommits(baseSha: string, headSha: string, signal?: AbortSignal): Promise<GitHubComparison> {
|
|
188
|
+
validateSha(baseSha)
|
|
189
|
+
validateSha(headSha)
|
|
190
|
+
// The changed files ride only on the first page of commits, so one commit per page keeps the rest of the body small.
|
|
191
|
+
const body = await this.#readGitObject(`/compare/${baseSha}...${headSha}?per_page=1`, signal, MAX_COMPARE_RESPONSE_BYTES)
|
|
192
|
+
return decodeComparison(body, headSha)
|
|
134
193
|
}
|
|
135
194
|
|
|
136
195
|
async createBranch(input: GitHubCreateBranchInput): Promise<GitHubRef> {
|
|
@@ -152,6 +211,15 @@ class RepositoryClient implements GitHubRepositoryClient {
|
|
|
152
211
|
return requireBranchAt(raced, input.fromSha)
|
|
153
212
|
}
|
|
154
213
|
|
|
214
|
+
async deleteBranch(branch: string, signal?: AbortSignal): Promise<{ readonly deleted: boolean }> {
|
|
215
|
+
validateBranch(branch)
|
|
216
|
+
const result = await this.#request(`/git/refs/heads/${encodeBranch(branch)}`, { method: 'DELETE', signal, expectedFailures: [422] })
|
|
217
|
+
if (result.ok) return { deleted: true }
|
|
218
|
+
// 422 is "Reference does not exist" among other refusals; only an absent branch counts as already deleted.
|
|
219
|
+
if (await this.readRef(branch, signal) !== null) throw requestStatusError(result.status)
|
|
220
|
+
return { deleted: false }
|
|
221
|
+
}
|
|
222
|
+
|
|
155
223
|
async commitFiles(input: GitHubCommitFilesInput): Promise<GitHubCommit> {
|
|
156
224
|
validateBranch(input.branch)
|
|
157
225
|
validateSha(input.expectedHeadSha)
|
|
@@ -288,6 +356,7 @@ class RepositoryClient implements GitHubRepositoryClient {
|
|
|
288
356
|
if (options.expectedFailures?.includes(response.status) === true) return { ok: false, status: response.status }
|
|
289
357
|
throw requestStatusError(response.status)
|
|
290
358
|
}
|
|
359
|
+
if (response.status === 204) return { ok: true, body: null }
|
|
291
360
|
return { ok: true, body: await readBoundedJson(response, cancellation, options.maxResponseBytes) }
|
|
292
361
|
} finally {
|
|
293
362
|
cancellation.dispose()
|
|
@@ -334,6 +403,17 @@ class TreeWalker {
|
|
|
334
403
|
}
|
|
335
404
|
}
|
|
336
405
|
|
|
406
|
+
type GitHubBlobEntry = Extract<GitHubTreeEntry, { readonly type: 'blob' }>
|
|
407
|
+
|
|
408
|
+
/** The entry when it is a regular file within both bounds, otherwise why it is not read. */
|
|
409
|
+
function readableBlob(entry: GitHubTreeEntry | null, remainingBytes: number): GitHubBlobEntry | GitHubUnreadableReason {
|
|
410
|
+
if (entry === null) return 'missing'
|
|
411
|
+
if (entry.type !== 'blob' || entry.mode === '120000') return 'not_a_file'
|
|
412
|
+
if (entry.size > MAX_FILE_BYTES) return 'too_large'
|
|
413
|
+
if (entry.size > remainingBytes) return 'budget'
|
|
414
|
+
return entry
|
|
415
|
+
}
|
|
416
|
+
|
|
337
417
|
function requireBranchAt(ref: GitHubRef, sha: string): GitHubRef {
|
|
338
418
|
if (ref.sha !== sha) throw new GitHubBranchConflictError()
|
|
339
419
|
return ref
|