Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import type { Project } from '../../shared/types'
import type {
CreateIssueInput,
CreateMappedLabelsResult,
GitHubIssue,
GitHubIssueCardView,
GitHubIssuePage,
GitHubIssueQuery,
GitHubMutationResult,
GitHubCloseReason,
GitHubRepositoryLabel,
GitHubThrottle,
IssueHeartbeatResult,
IssuePageResult,
LabelPageResult,
ListIssueOptions,
NormalisedProjectKanbanGitHub,
UpdateIssueInput
} from '../../shared/github-issues'
import type { GitHubAvatarFetcher } from './avatar-fetcher'
import {
GitHubCacheError,
type GitHubCompleteSnapshot,
type GitHubIssueCache
} from './cache'
import { classifyGitHubFailure } from './failure'
import type { GitHubRequestCoordinator } from './request-coordinator'
import type { PullStatusRead } from './graphql-pulls'
import { GitHubPullStatusTracker } from './pull-status-tracker'
import type { GitHubPullBoard, GitHubPullChecksResult, PullLifecycle } from '../../shared/github-pull-status'
const MAX_ISSUES = 10_000
const MAX_CACHE_BYTES = 64 * 1024 * 1024
const FULL_REFRESH_AGE = 24 * 60 * 60_000
const POLL_MS = 60_000
/** Where the heartbeat's validator lives inside the snapshot's (long-existing, previously always
* empty) `etags` map, so it is persisted with the issues it vouches for and survives a restart. */
export const HEARTBEAT_ETAG_KEY = 'heartbeat'
/** Floor between two caller-driven refreshes of one project, and the longer floor for a FULL
* reconciliation. `refresh` is reachable from the renderer AND — for a shared project — from a
* relay guest, and nothing else bounds it: `state.refresh` coalesces CONCURRENT calls but not
* sequential ones, so an unthrottled caller can restart a whole-repository scan as fast as the
* previous one completes and spend the host's entire hourly quota (which is the ACCOUNT's quota —
* it degrades the user's `gh` CLI and github.com session too, not just nodeterm). Both floors sit
* under POLL_MS so the background poll is never the thing they throttle. */
export const REFRESH_MIN_INTERVAL_MS = 30_000
export const FULL_REFRESH_MIN_INTERVAL_MS = 120_000
/** Check detail is read when a PR's modal opens — reachable from the renderer AND a relay guest,
* and each read is a GraphQL request plus a credential resolve. So: the same PR within this window
* shares one read, and a project gets at most `PULL_CHECKS_PER_MINUTE` reads a minute. Both are
* checked before anything is resolved or sent. */
export const PULL_CHECKS_REUSE_MS = 15_000
export const PULL_CHECKS_PER_MINUTE = 10
export interface GitHubIssuesClientLike {
listIssues(repository: string, options: ListIssueOptions): Promise<IssuePageResult>
issuesHeartbeat(repository: string, etag?: string): Promise<IssueHeartbeatResult>
getIssue(repository: string, issueNumber: number): Promise<GitHubIssue>
updateIssue(repository: string, issueNumber: number, input: UpdateIssueInput): Promise<GitHubIssue>
listRepositoryLabels(
repository: string,
options: { page: number; perPage: number; etag?: string }
): Promise<LabelPageResult>
createLabel(
repository: string,
input: { name: string; color: string; description?: string }
): Promise<GitHubRepositoryLabel>
/** Agent-filed gap reports (@core/github/report-issue-service). Declared here rather than only
* on the concrete client so `contextForProject` hands one caller everything it needs — the
* report path must never build a second authenticated client of its own. */
createIssue(repository: string, input: CreateIssueInput): Promise<GitHubIssue>
createIssueComment(repository: string, issueNumber: number, body: string): Promise<{ id: number }>
/** Pull request CI + mergeability (one GraphQL read). Optional so a client that cannot make
* GraphQL reads — and every test fake written before them — simply has no pull status: the board
* then shows none, which is the honest answer. */
pullRequestStatuses?(repository: string): Promise<PullStatusRead>
pullRequestChecks?(repository: string, pullNumber: number): Promise<GitHubPullChecksResult>
}
export interface GitHubIssueProjectContext {
localApprovalId: string
projectId: string
repository: string
config: NormalisedProjectKanbanGitHub
controlRevision: number
columnColors: Record<string, string>
/** This machine approved the column mapping now on disk (see `githubMappingDigest`). Without it
* the board reads but never writes: the mapping decides what a write DOES, and it arrives
* through the git-shared project file. */
mappingApproved: boolean
/** The project this context was resolved from (in-process only). The read-only control verbs use
* it so a call loads the workspace once, not a second time for the nodes and board. */
project?: Project
}
/** What `controlSnapshot` answers: the cached board state of one project, no request made. */
export interface GitHubControlSnapshot {
repository: string
/** The project the snapshot was resolved for (nodes, board columns, pull-link tombstones). */
project?: Project
completionColumnId?: string
mappingApproved: boolean
/** Issues AND pull requests of the harvest, each with the column its labels map it to. */
items: GitHubIssueCardView[]
/** A complete harvest exists (from this run or the on-disk cache). */
hasSnapshot: boolean
/** Only a partial harvest exists (the repository is over the issue/byte bounds). */
partial: boolean
incomplete: boolean
pullsTruncated: boolean
/** Epoch ms of the last complete refresh — how old the list is. */
lastSuccessfulRefreshAt?: number
pullBoard: GitHubPullBoard
throttle?: GitHubThrottle
}
export interface GitHubIssueServiceContext extends GitHubIssueProjectContext {
credentialGeneration: number
userId: string
client: GitHubIssuesClientLike
}
type TimerId = ReturnType<typeof setInterval> | number
type ServiceOptions = {
cache: GitHubIssueCache
coordinator: GitHubRequestCoordinator
contextForProject(projectId: string): Promise<GitHubIssueServiceContext>
projectContextForCache?(projectId: string): Promise<GitHubIssueProjectContext>
projectContextForCacheDeletion?(projectId: string): Promise<GitHubIssueProjectContext>
avatarFetcher?: GitHubAvatarFetcher
now?: () => number
setInterval?: (fn: () => void, milliseconds: number) => TimerId
clearInterval?: (timer: TimerId) => void
onDelta?: (uiId: number, projectId: string, changedIssueNumbers: number[]) => void
}
type RepositoryState = {
snapshot?: GitHubCompleteSnapshot
partialIssues?: GitHubIssue[]
incomplete: boolean
subscribers: Map<string, Set<number>>
timer?: TimerId
refresh?: Promise<void>
cacheGeneration: number
/** The throttle deadline subscribers were last prompted about, so a held poll re-prompts them
* once per deadline instead of once a minute. */
announcedThrottleUntil?: number
}
type RepositoryControl = {
generation: number
clearCutoff: number
deletion?: Promise<void>
}
function repositoryKey(context: GitHubIssueServiceContext): string {
return `${context.userId}\0${context.repository}`
}
function epoch(context: GitHubIssueServiceContext): string {
return JSON.stringify([
context.localApprovalId,
context.projectId,
context.repository,
context.config.revision,
context.controlRevision,
context.credentialGeneration,
context.userId
])
}
function foldLabel(value: string): string {
return value.normalize('NFKC').toLocaleLowerCase('en-US')
}
function mapping(issue: GitHubIssue, config: NormalisedProjectKanbanGitHub): {
columnId: string | null
conflict: GitHubIssueCardView['conflict']
} {
if (issue.state === 'closed') {
return { columnId: config.completionColumnId ?? null, conflict: null }
}
const labelNames = new Set(issue.labels.map((label) => foldLabel(label.name)))
const matches = config.columnMappings.filter((item) =>
labelNames.has(foldLabel(item.label)))
if (matches.length > 1) return { columnId: null, conflict: 'multiple-mapped-labels' }
if (matches.length === 1 && matches[0].columnId === config.completionColumnId) {
return { columnId: null, conflict: 'open-with-completion-label' }
}
return { columnId: matches[0]?.columnId ?? null, conflict: null }
}
/** Trims a harvest to a bound by dropping PULL REQUESTS first, oldest-updated first.
* Issues are never dropped to make room for a pull request: the issue lane shipped first and
* a repository big enough to overflow must degrade in the new half, not turn the board it
* already had read only. Returns null when the issues ALONE still miss the bound — that is the
* caller's existing incomplete path, unchanged. `fits` is a predicate so the same order serves
* the item count and the byte ceiling. */
export function evictPullsToFit(
items: GitHubIssue[],
fits: (candidate: GitHubIssue[]) => boolean
): { items: GitHubIssue[]; pullsTruncated: boolean } | null {
if (fits(items)) return { items, pullsTruncated: false }
const issues = items.filter((item) => !item.pull)
if (!fits(issues)) return null
const pulls = items.filter((item) => item.pull)
.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.number - a.number)
// Binary search the largest surviving prefix: `fits` may stringify the whole harvest, so
// dropping one at a time would be O(n²) on a repository near the ceiling.
let low = 0
let high = pulls.length - 1
while (low < high) {
const middle = Math.ceil((low + high) / 2)
if (fits([...issues, ...pulls.slice(0, middle)])) low = middle
else high = middle - 1
}
return { items: [...issues, ...pulls.slice(0, low)], pullsTruncated: true }
}
function mutationChain<T>(
chains: Map<string, Promise<void>>,
key: string,
operation: () => Promise<T>
): Promise<T> {
const previous = chains.get(key) ?? Promise.resolve()
let resolveResult: (value: T) => void
let rejectResult: (error: unknown) => void
const result = new Promise<T>((resolve, reject) => { resolveResult = resolve; rejectResult = reject })
const next = previous.then(async () => {
try { resolveResult(await operation()) } catch (error) { rejectResult(error) }
})
chains.set(key, next)
void next.finally(() => { if (chains.get(key) === next) chains.delete(key) })
return result
}
export class GitHubIssueService {
private readonly repositories = new Map<string, RepositoryState>()
private readonly projectKeys = new Map<string, string>()
private readonly issueChains = new Map<string, Promise<void>>()
private readonly repositoryControls = new Map<string, RepositoryControl>()
private readonly statePreparations = new Map<string, Set<Promise<RepositoryState>>>()
private readonly refreshFloors = new Map<string, { any: number; full: number }>()
/** Pull request CI/mergeability per repository key — see pull-status-tracker.ts. */
private readonly pulls: GitHubPullStatusTracker
private readonly checkReads = new Map<string, { at: number; result: Promise<GitHubPullChecksResult> }>()
private readonly checkStarts = new Map<string, number[]>()
private operationSequence = 0
private readonly now: () => number
private readonly schedule: NonNullable<ServiceOptions['setInterval']>
private readonly unschedule: NonNullable<ServiceOptions['clearInterval']>
constructor(private readonly options: ServiceOptions) {
this.now = options.now ?? Date.now
this.schedule = options.setInterval ?? ((fn, milliseconds) => setInterval(fn, milliseconds))
this.unschedule = options.clearInterval ?? ((timer) => clearInterval(timer as ReturnType<typeof setInterval>))
this.pulls = new GitHubPullStatusTracker({
coordinator: options.coordinator,
now: this.now,
onChanged: (key, changed) => {
const state = this.repositories.get(key)
if (state) this.emitDelta(state, changed, true)
},
memory: {
load: (userId, repository) => options.cache.loadPullMemory(userId, repository),
save: (userId, repository, memory) => options.cache.savePullMemory(userId, repository, memory)
},
harvest: (key) => {
const lifecycles = new Map<number, PullLifecycle>()
for (const item of this.repositories.get(key)?.snapshot?.issues ?? []) {
if (!item.pull) continue
lifecycles.set(item.number, item.state === 'closed'
? item.pull.mergedAt ? 'merged' : 'closed'
: item.pull.draft ? 'draft' : 'open')
}
return lifecycles
}
})
}
async subscribe(uiId: number, request: { projectId: string }): Promise<GitHubIssuePage> {
const context = await this.cacheContext(request.projectId)
const { key, state } = await this.cachedState(context)
const firstSubscriber = this.subscriberCount(state) === 0
let subscribers = state.subscribers.get(request.projectId)
if (!subscribers) {
subscribers = new Set()
state.subscribers.set(request.projectId, subscribers)
}
subscribers.add(uiId)
this.projectKeys.set(request.projectId, key)
if (firstSubscriber) {
if (!state.snapshot && !state.partialIssues) {
try { await this.refresh({ projectId: request.projectId }) } catch { /* offline cache remains readable */ }
} else {
void this.refresh({ projectId: request.projectId }).catch(() => undefined)
}
}
const activeKey = this.projectKeys.get(request.projectId)
this.ensureTimer(activeKey ? this.repositories.get(activeKey) ?? state : state)
return this.query({ projectId: request.projectId, columnId: null, pageSize: 50 })
}
unsubscribe(uiId: number, projectId: string): void {
const key = this.projectKeys.get(projectId)
const state = key ? this.repositories.get(key) : undefined
if (!state) return
const subscribers = state.subscribers.get(projectId)
subscribers?.delete(uiId)
if (subscribers?.size === 0) state.subscribers.delete(projectId)
if (this.subscriberCount(state) === 0 && state.timer) {
this.unschedule(state.timer)
delete state.timer
}
}
dropClient(uiId: number): void {
for (const state of this.repositories.values()) {
for (const [projectId, subscribers] of state.subscribers) {
subscribers.delete(uiId)
if (subscribers.size === 0) state.subscribers.delete(projectId)
}
if (this.subscriberCount(state) === 0 && state.timer) {
this.unschedule(state.timer)
delete state.timer
}
}
}
async refresh(request: { projectId: string; full?: boolean }): Promise<void> {
// The floor is checked BEFORE contextForProject on purpose: resolving a context runs the whole
// credential chain (gh subprocesses + a /user round trip), so a throttle placed after it would
// still pay the expensive half of every call it rejects.
const full = request.full === true
const startedAt = this.now()
const previousFloor = this.refreshFloors.get(request.projectId)
if (previousFloor && startedAt < (full ? previousFloor.full : previousFloor.any)) return
this.refreshFloors.set(request.projectId, {
any: startedAt + REFRESH_MIN_INTERVAL_MS,
// An incremental pass does not satisfy a full reconciliation, so it never moves that floor.
full: full ? startedAt + FULL_REFRESH_MIN_INTERVAL_MS : previousFloor?.full ?? 0
})
try {
// Reuse the clock read above as the refresh's own start stamp: one read per refresh keeps the
// incremental watermark anchored to when the work actually began.
// A foreground refresh is never held by the budget, so there is no throttle to hand back.
await this.refreshWithinFloor(request, startedAt)
} catch (error) {
// A refresh that FAILED bought nothing, so it must not hold the floor — otherwise the first
// network blip disables the board's own Retry button for the next 30 seconds.
if (this.refreshFloors.get(request.projectId)?.any === startedAt + REFRESH_MIN_INTERVAL_MS) {
if (previousFloor) this.refreshFloors.set(request.projectId, previousFloor)
else this.refreshFloors.delete(request.projectId)
}
throw error
}
}
/** Resolves to the throttle when a BACKGROUND refresh was held by the rate budget (nothing was
* sent), otherwise to nothing. */
private async refreshWithinFloor(
request: { projectId: string; full?: boolean },
startedAt = this.now(),
background = false
): Promise<GitHubThrottle | void> {
const operationId = ++this.operationSequence
const captured = await this.options.contextForProject(request.projectId)
if (background) {
// Checked after the context resolves because the budget belongs to an IDENTITY, and only the
// context knows which one. Nothing below this line has spent a request yet.
const throttle = this.options.coordinator.throttle(captured.userId)
if (throttle) return throttle
}
const control = this.repositoryControl(captured.repository)
if (control.deletion || operationId <= control.clearCutoff) return
const repositoryGeneration = control.generation
let state: RepositoryState
try {
state = await this.state(captured, operationId, repositoryGeneration)
} catch (error) {
if (error instanceof RepositoryClearedError) return
throw error
}
if (state.refresh) return state.refresh
const cacheGeneration = state.cacheGeneration
const work = this.refreshRepository(
captured, state, request.full === true, cacheGeneration, operationId, repositoryGeneration,
startedAt, background
)
state.refresh = work
try { await work } finally { if (state.refresh === work) delete state.refresh }
}
async query(request: GitHubIssueQuery): Promise<GitHubIssuePage> {
if (!Number.isSafeInteger(request.pageSize) || request.pageSize < 1 || request.pageSize > 50) {
throw new Error('invalid-query')
}
const context = await this.cacheContext(request.projectId)
const { state, userId } = await this.cachedState(context)
const throttle = userId ? this.options.coordinator.throttle(userId) : undefined
// One snapshot holds both kinds (they arrive on the same endpoint), so the kind filter is
// what keeps the issue lane's items and counts exactly what they were before pull requests
// were harvested. An absent kind means issues.
const wantPull = request.kind === 'pull'
const source = (state.snapshot?.issues ?? state.partialIssues ?? [])
.filter((item) => !!item.pull === wantPull)
const mapped = source.map((issue): GitHubIssueCardView => ({ ...issue, ...mapping(issue, context.config) }))
const search = request.search?.trim().toLocaleLowerCase('en-US') ?? ''
const filters = new Set((request.labelFilter ?? []).map((item) =>
foldLabel(item.replace(/^github:/, ''))))
const filtered = mapped.filter((item) => !search || item.title.toLocaleLowerCase('en-US').includes(search) ||
String(item.number).includes(search))
.filter((item) => filters.size === 0 || item.labels.some((label) =>
filters.has(foldLabel(label.name))))
const visible = filtered.filter((item) => item.columnId === request.columnId)
.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.number - a.number)
const offset = request.cursor ? Number(request.cursor) : 0
if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('invalid-query')
const page = visible.slice(offset, offset + request.pageSize)
if (this.options.avatarFetcher) {
const avatars = await this.options.avatarFetcher.forPage(page.flatMap((item) => item.assignees))
for (const item of page) {
const entries = item.assignees.flatMap((user) => {
const data = avatars.dataUrls.get(user.id)
return data ? [[String(user.id), data] as const] : []
})
if (entries.length) item.avatarDataUrls = Object.fromEntries(entries)
}
}
const counts: Record<string, number> = {}
for (const item of filtered) {
counts[item.columnId ?? 'ungrouped'] = (counts[item.columnId ?? 'ungrouped'] ?? 0) + 1
}
return {
items: page,
counts,
...(offset + page.length < visible.length ? { nextCursor: String(offset + page.length) } : {}),
partial: (!state.snapshot && !!state.partialIssues) ||
(wantPull && !!state.snapshot?.pullsTruncated),
// The board never writes a pull request, so its page says so on the wire rather than
// relying on every consumer to remember.
readOnly: wantPull || !context.mappingApproved ||
state.incomplete || !state.snapshot || !context.config.completionColumnId,
...(context.mappingApproved ? {} : { mappingNotApproved: true as const }),
...(state.snapshot ? {
lastSuccessfulRefreshAt: state.snapshot.lastSuccessfulRefreshAt,
lastFullReconciliationAt: state.snapshot.lastFullReconciliationAt
} : {}),
...(throttle ? { throttle } : {})
}
}
moveIssue(request: {
projectId: string
issueNumber: number
toColumnId: string | null
expectedUpdatedAt: string
closeReason?: GitHubCloseReason
}): Promise<GitHubMutationResult> {
// Reachable from the renderer and from a relay guest: an unknown reason is refused here, before
// anything is read or written, rather than forwarded for GitHub to reject after a round trip.
if (request.closeReason !== undefined &&
request.closeReason !== 'completed' && request.closeReason !== 'not_planned') {
return Promise.resolve({ status: 'invalid-target' })
}
const operationId = ++this.operationSequence
return mutationChain(this.issueChains, `${request.projectId}:${request.issueNumber}`, async () => {
const captured = await this.options.contextForProject(request.projectId)
const capturedEpoch = epoch(captured)
const repositoryGeneration = this.repositoryControl(captured.repository).generation
let state: RepositoryState
try {
state = await this.state(captured, operationId, repositoryGeneration)
} catch (error) {
if (error instanceof RepositoryClearedError) return { status: 'read-only' }
throw error
}
const cacheGeneration = state.cacheGeneration
if (!captured.mappingApproved || state.incomplete || !state.snapshot ||
!captured.config.completionColumnId) {
return { status: 'read-only' }
}
const target = state.snapshot.issues.find((item) => item.number === request.issueNumber)
// A pull request shares the issue number space and now lives in the same snapshot, so the
// membership check alone would let one through to a write path that cannot serve it.
if (!target || target.pull) return { status: 'invalid-target' }
if (capturedEpoch !== epoch(await this.options.contextForProject(request.projectId))) {
return { status: 'configuration-changed' }
}
const latest = await this.readWithEpoch(captured, () =>
captured.client.getIssue(captured.repository, request.issueNumber))
.catch((error: unknown) => error instanceof ConfigurationChangedError ? null : Promise.reject(error))
if (!latest) return { status: 'configuration-changed' }
if (latest.updatedAt !== request.expectedUpdatedAt) {
if (cacheGeneration !== state.cacheGeneration ||
!this.repositoryWriteAllowed(captured.repository, operationId, repositoryGeneration)) {
return { status: 'stale', issue: latest }
}
state.snapshot = {
...state.snapshot,
issues: state.snapshot.issues.map((item) => item.number === latest.number ? latest : item)
}
try {
await this.options.cache.saveComplete(captured.userId, captured.repository, state.snapshot)
} catch { /* the validated in-memory issue remains available for this process */ }
this.emitDelta(state, [latest.number])
return { status: 'stale', issue: latest }
}
const destination = request.toColumnId === null
? null
: captured.config.columnMappings.find((item) => item.columnId === request.toColumnId)
if (request.toColumnId !== null && !destination) return { status: 'invalid-target' }
const mappedNames = new Set(captured.config.columnMappings.map((item) =>
foldLabel(item.label)))
const labels = latest.labels.map((label) => label.name)
.filter((name) => !mappedNames.has(foldLabel(name)))
if (destination) labels.push(destination.label)
const desiredState = request.toColumnId === captured.config.completionColumnId
? 'closed'
: 'open'
const input: UpdateIssueInput = {
// Send `state` ONLY when it actually changes. GitHub rewrites `state_reason` for any write
// that carries `state`, so re-closing an already-closed issue turns a deliberate
// 'not_planned' (wontfix) into 'completed'. Closed issues all map into the completion
// column, so a drag that lands one back where it already sits is a no-op the user never
// meant as a state change — and it must not be one on GitHub either.
// When it DOES change, the reason travels with it: the one the user picked for a close
// (GitHub's own default, `completed`, when none was given), and `reopened` for a reopen.
...(latest.state === desiredState ? {} : {
state: desiredState,
stateReason: desiredState === 'closed' ? request.closeReason ?? 'completed' : 'reopened'
}),
labels
}
if (capturedEpoch !== epoch(await this.options.contextForProject(request.projectId))) {
return { status: 'configuration-changed' }
}
const updated = await this.options.coordinator.runMutation(captured.userId, async () => {
if (capturedEpoch !== epoch(await this.options.contextForProject(request.projectId))) {
throw new ConfigurationChangedError()
}
return captured.client.updateIssue(captured.repository, request.issueNumber, input)
}).catch((error: unknown) => {
if (error instanceof ConfigurationChangedError) return null
throw error
})
if (!updated) return { status: 'configuration-changed' }
const confirmedLabels = new Set(updated.labels.map((label) =>
label.name.normalize('NFKC').toLocaleLowerCase('en-US')))
const expectedLabels = new Set(labels.map((label) =>
label.normalize('NFKC').toLocaleLowerCase('en-US')))
if (updated.state !== desiredState ||
(input.state === 'closed' && updated.stateReason !== input.stateReason) ||
confirmedLabels.size !== expectedLabels.size ||
[...expectedLabels].some((label) => !confirmedLabels.has(label))) {
throw new Error('mutation-not-confirmed')
}
if (capturedEpoch !== epoch(await this.options.contextForProject(request.projectId))) {
return { status: 'confirmed', issue: updated }
}
if (cacheGeneration !== state.cacheGeneration) {
return { status: 'refresh-pending', issue: updated }
}
if (!this.repositoryWriteAllowed(captured.repository, operationId, repositoryGeneration)) {
return { status: 'refresh-pending', issue: updated }
}
// The write folds ONE issue into the snapshot and leaves `lastSuccessfulRefreshAt` alone: that
// is the incremental scan's `since` cursor, and only a completed scan has looked at everything
// up to it. Advancing it here skipped any third party's change that landed between the last
// scan and this write until the next daily full reconciliation.
const snapshot = state.snapshot ?? {
issues: [], etags: {}, lastSuccessfulRefreshAt: 0, lastFullReconciliationAt: 0
}
const issues = snapshot.issues.some((item) => item.number === updated.number)
? snapshot.issues.map((item) => item.number === updated.number ? updated : item)
: [...snapshot.issues, updated]
state.snapshot = { ...snapshot, issues }
state.partialIssues = undefined
try {
await this.options.cache.saveComplete(captured.userId, captured.repository, state.snapshot)
} catch {
return { status: 'refresh-pending', issue: updated }
}
this.emitDelta(state, [updated.number])
return { status: 'confirmed', issue: updated }
})
}
async createMissingLabels(request: { projectId: string }): Promise<CreateMappedLabelsResult> {
const operationId = ++this.operationSequence
const captured = await this.options.contextForProject(request.projectId)
const capturedEpoch = epoch(captured)
const repositoryGeneration = this.repositoryControl(captured.repository).generation
let state: RepositoryState
try {
state = await this.state(captured, operationId, repositoryGeneration)
} catch (error) {
if (error instanceof RepositoryClearedError) {
return { status: 'read-only', created: [], remaining:
captured.config.columnMappings.map((item) => item.label) }
}
throw error
}
// Label names come from the column mapping, so creating them is a write the mapping drives.
if (!captured.mappingApproved || state.incomplete || !captured.config.completionColumnId) {
return {
status: 'read-only',
created: [],
remaining: captured.config.columnMappings.map((item) => item.label)
}
}
const known = new Set<string>()
let page = 1
while (true) {
if (capturedEpoch !== epoch(await this.options.contextForProject(request.projectId))) {
return {
status: 'configuration-changed',
created: [],
remaining: captured.config.columnMappings.map((item) => item.label)
}
}
const result = await this.readWithEpoch(captured, () =>
captured.client.listRepositoryLabels(captured.repository, { page, perPage: 100 }))
.catch((error: unknown) => error instanceof ConfigurationChangedError ? null : Promise.reject(error))
if (!result) {
return { status: 'configuration-changed', created: [], remaining:
captured.config.columnMappings.map((item) => item.label) }
}
for (const label of result.items) known.add(label.name.normalize('NFKC').toLocaleLowerCase('en-US'))
if (!result.nextPage) break
page = result.nextPage
}
const pending = captured.config.columnMappings.filter((item) =>
!known.has(item.label.normalize('NFKC').toLocaleLowerCase('en-US')))
const created: string[] = []
for (let index = 0; index < pending.length; index++) {
const item = pending[index]
if (capturedEpoch !== epoch(await this.options.contextForProject(request.projectId))) {
return {
status: 'configuration-changed',
created,
remaining: pending.filter((candidate) => !created.includes(candidate.label))
.map((candidate) => candidate.label)
}
}
const current = await this.repositoryLabelNames(captured).catch((error: unknown) =>
error instanceof ConfigurationChangedError ? null : Promise.reject(error))
if (!current) {
return {
status: 'configuration-changed', created,
remaining: pending.slice(index).map((candidate) => candidate.label)
}
}
const folded = item.label.normalize('NFKC').toLocaleLowerCase('en-US')
if (current.has(folded)) continue
const color = captured.columnColors[item.columnId]?.replace(/^#/, '')
const result = await this.options.coordinator.runMutation(captured.userId, async () => {
if (capturedEpoch !== epoch(await this.options.contextForProject(request.projectId))) {
throw new ConfigurationChangedError()
}
return captured.client.createLabel(captured.repository, {
name: item.label,
color: color && /^[0-9a-fA-F]{6}$/.test(color) ? color.toLowerCase() : '8b5cf6'
})
}).catch(async (error: unknown) => {
if (error instanceof ConfigurationChangedError) return null
const after = await this.repositoryLabelNames(captured).catch(() => null)
if (after?.has(folded)) return { concurrent: true } as const
return { failed: true } as const
})
if (!result) {
return {
status: 'configuration-changed',
created,
remaining: pending.filter((candidate) => !created.includes(candidate.label))
.map((candidate) => candidate.label)
}
}
if ('failed' in result) {
return {
status: 'partial', created,
remaining: pending.slice(index).map((candidate) => candidate.label)
}
}
if ('concurrent' in result) {
known.add(folded)
} else {
known.add(result.name.normalize('NFKC').toLocaleLowerCase('en-US'))
created.push(item.label)
}
}
return { status: 'confirmed', created, remaining: [] }
}
async clearCache(request: { projectId: string }): Promise<void> {
const clearOperationId = ++this.operationSequence
const context = this.options.projectContextForCacheDeletion
? await this.options.projectContextForCacheDeletion(request.projectId)
: await this.cacheContext(request.projectId)
const control = this.repositoryControl(context.repository)
if (control.deletion) await control.deletion
let finishDeletion!: () => void
const deletion = new Promise<void>((resolve) => { finishDeletion = resolve })
control.clearCutoff = Math.max(control.clearCutoff, clearOperationId)
control.generation += 1
control.deletion = deletion
try {
const affected = this.repositoryStates(context.localApprovalId, context.repository)
for (const state of affected) state.cacheGeneration += 1
const mutations = [...this.issueChains.values()]
await Promise.allSettled([
...this.statePreparations.get(context.repository) ?? [],
...affected.flatMap((state) => state.refresh ? [state.refresh] : []),
...mutations,
// Forgotten BEFORE the files go, and waited for: a memory save already under way would
// otherwise write the pull memory back after clearBound deleted it.
this.pulls.forgetRepository(context.repository)
])
await this.options.cache.clearBound(context.localApprovalId, context.projectId, context.repository)
for (const state of this.repositoryStates(context.localApprovalId, context.repository)) {
state.cacheGeneration += 1
state.snapshot = undefined
state.partialIssues = undefined
state.incomplete = false
this.emitDelta(state, [], true)
}
} finally {
if (control.deletion === deletion) delete control.deletion
finishDeletion()
}
}
/** What the board knows about this project's pull requests beyond the issues harvest. Read from
* memory only — it never sends a request. */
async pullStatus(request: { projectId: string }): Promise<GitHubPullBoard> {
const context = await this.cacheContext(request.projectId)
const { key } = await this.cachedState(context)
return this.pulls.board(key)
}
/**
* Everything the read-only control verbs (`issues` / `prs`, core/github/control-read.ts) show, from
* what this process ALREADY holds: the issue cache and the pull tracker's memory. It sends no
* request, resolves no credential and starts no poll — an agent's read must never spend the
* account's GitHub budget or wake a repository nobody has subscribed to. Throws the host's coded
* errors (`not-approved`, `invalid-configuration`, …) exactly like `query`, so a caller can say
* WHY there is nothing to show rather than "0 issues".
*/
async controlSnapshot(projectId: string): Promise<GitHubControlSnapshot> {
const context = await this.cacheContext(projectId)
const { key, state, userId } = await this.cachedState(context)
const source = state.snapshot?.issues ?? state.partialIssues ?? []
const throttle = userId ? this.options.coordinator.throttle(userId) : undefined
return {
repository: context.repository,
...(context.project ? { project: context.project } : {}),
completionColumnId: context.config.completionColumnId,
mappingApproved: context.mappingApproved,
items: source.map((issue): GitHubIssueCardView => ({ ...issue, ...mapping(issue, context.config) })),
hasSnapshot: !!state.snapshot,
partial: !state.snapshot && !!state.partialIssues,
incomplete: state.incomplete,
pullsTruncated: !!state.snapshot?.pullsTruncated,
...(state.snapshot ? { lastSuccessfulRefreshAt: state.snapshot.lastSuccessfulRefreshAt } : {}),
pullBoard: this.pulls.board(key),
...(throttle ? { throttle } : {})
}
}
/**
* A VISIBLE board asks this while some PR is undecided. It answers false at the cost of a map
* lookup unless a chase read is due, so a board may ask as often as it likes: the schedule and the
* cap of 12 live here, and only a due read resolves a context (which runs the credential chain).
*/
async chasePulls(request: { projectId: string }): Promise<boolean> {
const key = this.projectKeys.get(request.projectId)
if (!key || !this.pulls.claimChase(key)) return false
let captured: GitHubIssueServiceContext
try {
captured = await this.options.contextForProject(request.projectId)
} catch {
return false
}
if (repositoryKey(captured) !== key || !captured.client.pullRequestStatuses) return false
await this.pulls.read(key, captured.userId, 'chase', () =>
this.readWithEpoch(captured, () => captured.client.pullRequestStatuses!(captured.repository)))
return true
}
/**
* The one-time permission for the board to move `cardId` because every PR in `pulls` merged. The
* first ask wins across every window (two Server Edition tabs cannot both move it), and it is
* remembered per PR, so a card the user dragged back is not moved again for the same merges — even
* after one of them ages off the pull board. It sends no request and resolves no credential.
*/
async claimPullAutoMove(request: { projectId: string; cardId: string; pulls: number[] }): Promise<boolean> {
const key = this.validPullCardRequest(request)
if (!key) return false
const { projectId, cardId, pulls } = request
return this.pulls.claimMove(key, projectId, cardId, pulls)
}
/**
* A visible, armed board reports "this card is waiting on these still-open PRs". The host keeps a
* note only for PRs it holds as open itself; `claimPullAutoMove` later requires one. Sends no
* request and resolves no credential.
*/
async notePullWaits(request: { projectId: string; cardId: string; pulls: number[] }): Promise<number> {
const key = this.validPullCardRequest(request)
if (!key) return 0
return this.pulls.noteWaits(key, request.projectId, request.cardId, request.pulls)
}
/** The repository key for a well-formed card request on a bound project that is not being cleared. */
private validPullCardRequest(
request: { projectId: string; cardId: string; pulls: number[] } | null | undefined
): string | null {
const { projectId, cardId, pulls } = request ?? {}
if (typeof projectId !== 'string' || typeof cardId !== 'string' || !cardId || cardId.length > 256 ||
/[\u0000-\u001f]/.test(cardId) || !Array.isArray(pulls) || pulls.length === 0 || pulls.length > 100 ||
pulls.some((pull) => !Number.isSafeInteger(pull) || pull < 1)) return null
const key = this.projectKeys.get(projectId)
if (!key || key.startsWith('unbound:')) return null
if (this.repositoryControl(key.slice(key.indexOf('\0') + 1)).deletion) return null
return key
}
/** Per-check detail for one PR, read when its modal opens. Never throws: every failure is one of
* the result's own statuses, so a modal can always say what it knows. */
async pullChecks(request: { projectId: string; pullNumber: number }): Promise<GitHubPullChecksResult> {
if (!Number.isSafeInteger(request.pullNumber) || request.pullNumber < 1) {
return { status: 'unavailable' }
}
const now = this.now()
const key = `${request.projectId}\0${request.pullNumber}`
const recent = this.checkReads.get(key)
if (recent && now - recent.at < PULL_CHECKS_REUSE_MS) return recent.result
const starts = (this.checkStarts.get(request.projectId) ?? []).filter((at) => now - at < 60_000)
if (starts.length >= PULL_CHECKS_PER_MINUTE) {
this.checkStarts.set(request.projectId, starts)
return { status: 'unavailable' }
}
this.checkStarts.set(request.projectId, [...starts, now])
for (const [candidate, entry] of this.checkReads) {
if (now - entry.at >= PULL_CHECKS_REUSE_MS) this.checkReads.delete(candidate)
}
const result = this.readPullChecks(request)
this.checkReads.set(key, { at: now, result })
return result
}
private async readPullChecks(request: { projectId: string; pullNumber: number }): Promise<GitHubPullChecksResult> {
let captured: GitHubIssueServiceContext
try {
captured = await this.options.contextForProject(request.projectId)
} catch {
return { status: 'unavailable' }
}
if (!captured.client.pullRequestChecks) return { status: 'unavailable' }
// A token already known to be unable to read checks is not asked again.
if (!this.pulls.board(repositoryKey(captured)).access.ci) return { status: 'hidden' }
const throttle = this.options.coordinator.throttle(captured.userId, this.now(), 'graphql')
if (throttle?.kind === 'rate-limited') return { status: 'unavailable' }
try {
return await this.readWithEpoch(captured, () =>
captured.client.pullRequestChecks!(captured.repository, request.pullNumber))
} catch (error) {
// A 403 that is not a rate limit: this token may not read the checks. Say nothing about them.
return (error as { code?: unknown } | null)?.code === 'insufficient-permission'
? { status: 'hidden' }
: { status: 'unavailable' }
}
}
private readPullStatusAfterHeartbeat(
captured: GitHubIssueServiceContext,
changed: boolean,
foreground: boolean
): void {
const key = repositoryKey(captured)
if (!captured.client.pullRequestStatuses) return
if (!this.pulls.wantsReadAfterHeartbeat(key, { changed, foreground })) return
void this.pulls.read(key, captured.userId, foreground ? 'foreground' : 'heartbeat', () =>
this.readWithEpoch(captured, () => captured.client.pullRequestStatuses!(captured.repository)))
.catch(() => undefined)
}
private state(
context: GitHubIssueServiceContext,
operationId: number,
repositoryGeneration: number
): Promise<RepositoryState> {
const work = this.prepareState(context, operationId, repositoryGeneration)
let preparations = this.statePreparations.get(context.repository)
if (!preparations) {
preparations = new Set()
this.statePreparations.set(context.repository, preparations)
}
preparations.add(work)
void work.finally(() => {
preparations!.delete(work)
if (preparations!.size === 0) this.statePreparations.delete(context.repository)
}).catch(() => undefined)
return work
}
private async prepareState(
context: GitHubIssueServiceContext,
operationId: number,
repositoryGeneration: number
): Promise<RepositoryState> {
this.assertRepositoryWriteAllowed(context.repository, operationId, repositoryGeneration)
await this.options.cache.bind(
context.localApprovalId, context.projectId, context.repository, context.userId
)
this.assertRepositoryWriteAllowed(context.repository, operationId, repositoryGeneration)
const key = repositoryKey(context)
const unboundKey = `unbound:${context.localApprovalId}\0${context.repository}`
const unbound = this.repositories.get(unboundKey)
let state = this.repositories.get(key)
if (!state) {
const cached = await this.options.cache.load(context.userId, context.repository)
this.assertRepositoryWriteAllowed(context.repository, operationId, repositoryGeneration)
state = {
snapshot: cached.lastComplete,
partialIssues: cached.lastAttempt?.partialIssues,
incomplete: !!cached.lastAttempt,
subscribers: new Map(),
cacheGeneration: 0
}
this.repositories.set(key, state)
}
if (unbound && unbound !== state) {
for (const [projectId, subscribers] of unbound.subscribers) {
let target = state.subscribers.get(projectId)
if (!target) {
target = new Set()
state.subscribers.set(projectId, target)
}
for (const uiId of subscribers) target.add(uiId)
}
if (unbound.timer) {
this.unschedule(unbound.timer)
delete unbound.timer
}
this.repositories.delete(unboundKey)
this.ensureTimer(state)
}
this.migrateProjectState(context.projectId, key, state)
this.projectKeys.set(context.projectId, key)
return state
}
private async cacheContext(projectId: string): Promise<GitHubIssueProjectContext> {
if (this.options.projectContextForCache) return this.options.projectContextForCache(projectId)
return this.options.contextForProject(projectId)
}
private async cachedState(context: GitHubIssueProjectContext): Promise<{
key: string
state: RepositoryState
/** The identity the project's cache is bound to; null before its first authenticated refresh. */
userId: string | null
}> {
await this.waitForRepositoryDeletion(context.repository)
const repositoryGeneration = this.repositoryControl(context.repository).generation
const userId = await this.options.cache.boundUserId(
context.localApprovalId, context.projectId, context.repository
)
if (!userId) {
if (repositoryGeneration !== this.repositoryControl(context.repository).generation) {
return this.cachedState(context)
}
const key = `unbound:${context.localApprovalId}\0${context.repository}`
let state = this.repositories.get(key)
if (!state) {
state = { incomplete: false, subscribers: new Map(), cacheGeneration: 0 }
this.repositories.set(key, state)
}
this.projectKeys.set(context.projectId, key)
if (repositoryGeneration !== this.repositoryControl(context.repository).generation) {
return this.cachedState(context)
}
return { key, state, userId: null }
}
const key = `${userId}\0${context.repository}`
let state = this.repositories.get(key)
if (!state) {
const cached = await this.options.cache.load(userId, context.repository)
if (repositoryGeneration !== this.repositoryControl(context.repository).generation) {
return this.cachedState(context)
}
state = {
snapshot: cached.lastComplete,
partialIssues: cached.lastAttempt?.partialIssues,
incomplete: !!cached.lastAttempt,
subscribers: new Map(),
cacheGeneration: 0
}
this.repositories.set(key, state)
}
this.projectKeys.set(context.projectId, key)
if (repositoryGeneration !== this.repositoryControl(context.repository).generation) {
return this.cachedState(context)
}
return { key, state, userId }
}
private async refreshRepository(
captured: GitHubIssueServiceContext,
state: RepositoryState,
forceFull: boolean,
cacheGeneration: number,
operationId: number,
repositoryGeneration: number,
refreshStartedAt: number,
background = false
): Promise<void> {
const full = forceFull || !state.snapshot ||
this.now() - state.snapshot.lastFullReconciliationAt >= FULL_REFRESH_AGE
const previous = state.snapshot
const byNumber = new Map((full ? [] : previous?.issues ?? []).map((issue) => [issue.number, issue]))
// An incremental pass starts from a set a previous eviction may already have thinned, and it
// never re-fetches what was dropped — so the claim survives until a full reconciliation
// re-reads the repository and can honestly clear it.
let pullsTruncated = !full && !!previous?.pullsTruncated
// The heartbeat runs BEFORE the scan, and it is its validator — not one read afterwards — that
// gets stored: a change landing while the scan pages is then still "new" to the next heartbeat.
// A 304 skips the scan outright. It never skips a full reconciliation (deletions and transfers
// do not move the top item, so that pass is the only thing that can see them), and never an
// incomplete repository, which a 304 would otherwise freeze read only.
const storedEtag = previous?.etags[HEARTBEAT_ETAG_KEY]
const beat = await this.readWithEpoch(captured, () =>
captured.client.issuesHeartbeat(captured.repository, storedEtag))
.catch((error: unknown) =>
error instanceof ConfigurationChangedError ? null : Promise.reject(error))
if (!beat) return
// The heartbeat is also what decides whether pull request CI/mergeability is worth a GraphQL
// read. It runs beside the issue scan, not after it: the board's issues never wait on it.
this.readPullStatusAfterHeartbeat(captured, !beat.notModified, !background)
if (beat.notModified && !full && previous && !state.incomplete) {
// Nothing to fetch — but subscribers still re-read their pages, from the local cache, as every
// successful refresh has always made them do. A page is not only issues: read only, the
// mapping approval and the completion column are derived by the host at query time, and a
// board never prompted keeps showing the old answer (e.g. read only after its approval).
this.emitDelta(state, [], true)
return
}
const heartbeatEtag = beat.etag
const etags: Record<string, string> = heartbeatEtag ? { [HEARTBEAT_ETAG_KEY]: heartbeatEtag } : {}
let page = 1
while (true) {
if (!this.repositoryWriteAllowed(captured.repository, operationId, repositoryGeneration) ||
cacheGeneration !== state.cacheGeneration ||
epoch(captured) !== epoch(await this.options.contextForProject(captured.projectId))) return
const since = !full && previous?.lastSuccessfulRefreshAt
? new Date(Math.max(0, previous.lastSuccessfulRefreshAt - 2_000)).toISOString()
: undefined
const result = await this.readWithEpoch(captured, () =>
captured.client.listIssues(captured.repository, {
state: 'all', page, perPage: 100, ...(since ? { since } : {})
})).catch((error: unknown) =>
error instanceof ConfigurationChangedError ? null : Promise.reject(error))
if (!result) return
if (!result.notModified) {
for (const item of result.items) {
const old = byNumber.get(item.number)
if (!old || item.updatedAt >= old.updatedAt) byNumber.set(item.number, item)
}
}
if (byNumber.size > MAX_ISSUES) {
const trimmed = evictPullsToFit(
[...byNumber.values()], (candidate) => candidate.length <= MAX_ISSUES
)
if (!trimmed) {
await this.incomplete(
captured, state, 'issue-limit', [...byNumber.values()].slice(0, MAX_ISSUES),
cacheGeneration, operationId, repositoryGeneration
)
return
}
// Paging continues on the trimmed set: each firing drops at least one item, so the scan
// stays bounded, and a later page's issue still displaces a pull request rather than the
// scan giving up.
byNumber.clear()
for (const item of trimmed.items) byNumber.set(item.number, item)
pullsTruncated = pullsTruncated || trimmed.pullsTruncated
}
if (!result.nextPage) break
page = result.nextPage
}
const harvest = [...byNumber.values()]
const withinBytes = evictPullsToFit(harvest, (candidate) =>
Buffer.byteLength(JSON.stringify(candidate), 'utf-8') <= MAX_CACHE_BYTES)
if (!withinBytes) {
await this.incomplete(
captured, state, 'byte-limit', harvest, cacheGeneration, operationId, repositoryGeneration
)
return
}
const issues = withinBytes.items
pullsTruncated = pullsTruncated || withinBytes.pullsTruncated
if (!this.repositoryWriteAllowed(captured.repository, operationId, repositoryGeneration) ||
cacheGeneration !== state.cacheGeneration ||
epoch(captured) !== epoch(await this.options.contextForProject(captured.projectId))) return
const snapshot: GitHubCompleteSnapshot = {
issues,
etags,
lastSuccessfulRefreshAt: refreshStartedAt,
lastFullReconciliationAt: full
? refreshStartedAt
: previous?.lastFullReconciliationAt ?? refreshStartedAt,
...(pullsTruncated ? { pullsTruncated: true } : {})
}
if (!this.repositoryWriteAllowed(captured.repository, operationId, repositoryGeneration)) return
await this.options.cache.saveComplete(captured.userId, captured.repository, snapshot)
if (!this.repositoryWriteAllowed(captured.repository, operationId, repositoryGeneration) ||
cacheGeneration !== state.cacheGeneration) return
const oldNumbers = new Map((previous?.issues ?? []).map((item) => [item.number, item.updatedAt]))
const nextNumbers = new Set(issues.map((item) => item.number))
const changed = [
...issues.filter((item) => oldNumbers.get(item.number) !== item.updatedAt)
.map((item) => item.number),
...(previous?.issues ?? []).filter((item) => !nextNumbers.has(item.number))
.map((item) => item.number)
]
state.snapshot = snapshot
state.partialIssues = undefined
state.incomplete = false
this.emitDelta(state, changed, true)
}
private subscriberCount(state: RepositoryState): number {
let count = 0
for (const subscribers of state.subscribers.values()) count += subscribers.size
return count
}
private ensureTimer(state: RepositoryState): void {
if (state.timer || this.subscriberCount(state) === 0) return
state.timer = this.schedule(() => this.poll(state), POLL_MS)
}
private async poll(state: RepositoryState): Promise<void> {
for (const projectId of [...state.subscribers.keys()]) {
try {
// Deliberately BELOW the caller floor: the floor bounds callers we don't control (the
// renderer, and a relay guest on a shared project), while the poll is already paced by
// POLL_MS. Routing it through the floor would also break this loop's fallback — a
// throttled call returns without throwing, which reads here as "this project worked" and
// would stop us ever trying the next subscriber's context.
// It IS a background refresh, though, so the rate budget may hold it.
const throttle = await this.refreshWithinFloor({ projectId }, undefined, true)
// A refresh that ran prompted its subscribers itself (a 304 included), which is also what
// clears a lifted "held until" line from the board.
if (throttle) this.announceThrottle(state, throttle.until)
return
} catch (error) {
const failure = classifyGitHubFailure(error)
if (failure.kind === 'rate-limited' && failure.retryAt !== undefined) {
this.announceThrottle(state, failure.retryAt)
}
// Another approved project may still provide a valid context for the shared repository.
}
}
}
/** A held poll changes nothing the board can see except WHY it is quiet. Prompt its subscribers
* to re-read (the page carries the throttle) — once per deadline, not once per skipped minute. */
private announceThrottle(state: RepositoryState, until: number): void {
if (state.announcedThrottleUntil === until) return
state.announcedThrottleUntil = until
this.emitDelta(state, [], true)
}
/** Prompts one project's subscribers to re-read their pages. For a change the host makes that
* no refresh would report — an approval given or withdrawn — so the board does not wait for the
* next poll (or, before polls re-prompted, for something to change on GitHub). */
notifyProject(projectId: string): void {
const key = this.projectKeys.get(projectId)
const state = key ? this.repositories.get(key) : undefined
for (const uiId of state?.subscribers.get(projectId) ?? []) {
this.options.onDelta?.(uiId, projectId, [])
}
}
private migrateProjectState(projectId: string, key: string, target: RepositoryState): void {
const previousKey = this.projectKeys.get(projectId)
if (!previousKey || previousKey === key) return
const previous = this.repositories.get(previousKey)
const subscribers = previous?.subscribers.get(projectId)
if (!previous || !subscribers) return
let destination = target.subscribers.get(projectId)
if (!destination) {
destination = new Set()
target.subscribers.set(projectId, destination)
}
for (const uiId of subscribers) destination.add(uiId)
previous.subscribers.delete(projectId)
if (this.subscriberCount(previous) === 0 && previous.timer) {
this.unschedule(previous.timer)
delete previous.timer
}
this.ensureTimer(target)
}
private repositoryControl(repository: string): RepositoryControl {
let control = this.repositoryControls.get(repository)
if (!control) {
control = { generation: 0, clearCutoff: 0 }
this.repositoryControls.set(repository, control)
}
return control
}
private repositoryWriteAllowed(
repository: string,
operationId: number,
repositoryGeneration: number
): boolean {
const control = this.repositoryControl(repository)
return !control.deletion && operationId > control.clearCutoff &&
repositoryGeneration === control.generation
}
private assertRepositoryWriteAllowed(
repository: string,
operationId: number,
repositoryGeneration: number
): void {
if (!this.repositoryWriteAllowed(repository, operationId, repositoryGeneration)) {
throw new RepositoryClearedError()
}
}
private async waitForRepositoryDeletion(repository: string): Promise<void> {
while (this.repositoryControl(repository).deletion) {
await this.repositoryControl(repository).deletion
}
}
private repositoryStates(localApprovalId: string, repository: string): RepositoryState[] {
const states: RepositoryState[] = []
for (const [key, state] of this.repositories) {
if (key.endsWith(`\0${repository}`) || key === `unbound:${localApprovalId}\0${repository}`) {
states.push(state)
}
}
return states
}
private readWithEpoch<T>(captured: GitHubIssueServiceContext, operation: () => Promise<T>): Promise<T> {
return this.options.coordinator.runRead(captured.userId, async () => {
if (epoch(captured) !== epoch(await this.options.contextForProject(captured.projectId))) {
throw new ConfigurationChangedError()
}
return operation()
})
}
private async repositoryLabelNames(captured: GitHubIssueServiceContext): Promise<Set<string>> {
const names = new Set<string>()
let page = 1
while (true) {
const result = await this.readWithEpoch(captured, () =>
captured.client.listRepositoryLabels(captured.repository, { page, perPage: 100 }))
for (const label of result.items) {
names.add(label.name.normalize('NFKC').toLocaleLowerCase('en-US'))
}
if (!result.nextPage) return names
page = result.nextPage
}
}
private emitDelta(
state: RepositoryState,
changedIssueNumbers: number[],
includeEmpty = false
): void {
if (!includeEmpty && changedIssueNumbers.length === 0) return
for (const [projectId, subscribers] of state.subscribers) {
for (const uiId of subscribers) this.options.onDelta?.(uiId, projectId, changedIssueNumbers)
}
}
private async incomplete(
context: GitHubIssueServiceContext,
state: RepositoryState,
reason: 'issue-limit' | 'byte-limit',
issues: GitHubIssue[],
cacheGeneration: number,
operationId: number,
repositoryGeneration: number
): Promise<void> {
if (!this.repositoryWriteAllowed(context.repository, operationId, repositoryGeneration) ||
cacheGeneration !== state.cacheGeneration) return
await this.options.cache.saveIncompleteAttempt(context.userId, context.repository, {
reason,
observedAt: this.now(),
...(!state.snapshot ? { partialIssues: issues } : {})
})
if (!this.repositoryWriteAllowed(context.repository, operationId, repositoryGeneration) ||
cacheGeneration !== state.cacheGeneration) return
if (!state.snapshot) state.partialIssues = issues
state.incomplete = true
this.emitDelta(state, [], true)
}
}
/** Carries a `code` like every other error the pull status tracker reads: a context that changed
* mid-read is not a failed read, and must not mark the board stale. */
class ConfigurationChangedError extends Error {
readonly code = 'configuration-changed'
}
class RepositoryClearedError extends Error {}