Line
Version next
Search GitHub

You are reading the unreleased docs (next). See latest (v0.9)

ui/server/src/repoConnection

"Connect GitHub for private repositories": a second, opt-in consent that lets the Cockpit clone a private repository with the signed-in person's own GitHub access, with no token pasted.

Cockpit server, next. Source: ui/server/src/repoConnection.mjs.

Variables#

DEFAULT_API_BASE#

const DEFAULT_API_BASE: "https://api.github.com" = 'https://api.github.com'

Defined in: ui/server/src/repoConnection.mjs:27

DEFAULT_OAUTH_BASE#

const DEFAULT_OAUTH_BASE: "https://github.com" = 'https://github.com'

Defined in: ui/server/src/repoConnection.mjs:26

MAX_PENDING_PER_KEY#

const MAX_PENDING_PER_KEY: 3 = 3

Defined in: ui/server/src/repoConnection.mjs:36

review: pending states ONE session may hold; the oldest of that session goes first, so a session that keeps starting connections evicts its own, never another session's in-flight one. The global cap stays as the backstop.

PENDING_TTL_MS#

const PENDING_TTL_MS: number

Defined in: ui/server/src/repoConnection.mjs:28

REFRESH_MARGIN_MS#

const REFRESH_MARGIN_MS: number

Defined in: ui/server/src/repoConnection.mjs:30

Refresh an expiring access token this long before it runs out.

REPOS_CACHE_MS#

const REPOS_CACHE_MS: number

Defined in: ui/server/src/repoConnection.mjs:39

review: how long a session's repository listing is kept, so a picker that refreshes, filters or pages does not fan out to GitHub (up to 1 + installations x pages calls) on every request. Forgotten with the connection.

REQUEST_TIMEOUT_MS#

const REQUEST_TIMEOUT_MS: 8000 = 8000

Defined in: ui/server/src/repoConnection.mjs:31

Functions#

createRepoConnections()#

createRepoConnections(config, deps?): object

Defined in: ui/server/src/repoConnection.mjs:98

Parameters#

config
apiBase

string

authorizeUrl

string = ...

callbackUrl

string

clientId

string

clientSecret

string

enabled

boolean

halfConfigured

boolean

scope

string = ...

tokenUrl

string = ...

deps?

maxTtlMs: the longest a connection may live (the Cockpit session's own lifetime).

fetchImpl?

(input, init?) => Promise<Response>

maxTtlMs?

number

now?

() => number

randomToken?

() => string

registerExit?

boolean

sweepMs?

number

timeoutMs?

number

Returns#

acquire

acquire: (key) => Promise<any>

A Buffer COPY of the session's current access token (the caller zeroes it), refreshed first when it is about to expire, or null when there is no live connection.

Parameters
key

any

Returns

Promise<any>

begin

begin: (key) => object

Start an authorization for this session: -> { state, url } (the provider page to send the browser to).

Parameters
key

any

Returns

object

state

state: any

url

url: string

close

close: () => void

Stop the sweeper and wipe everything (tests; also what "server stop" does).

Returns

void

complete

complete: (__namedParameters) => Promise<{ code: string; error: string; login?: undefined; ok: boolean; } | { code?: undefined; error?: undefined; login: any; ok: boolean; }>

Finish an authorization: exchange the code, learn whose GitHub account it is, keep the token in memory. -> { ok:true, login } | { ok:false, code, error } (fixed wording; nothing from the provider is echoed).

Parameters
__namedParameters
code

any

key

any

state

any

Returns

Promise<{ code: string; error: string; login?: undefined; ok: boolean; } | { code?: undefined; error?: undefined; login: any; ok: boolean; }>

config

config: object

config.apiBase

apiBase: string

config.authorizeUrl

authorizeUrl: string

config.callbackUrl

callbackUrl: string

config.clientId

clientId: string

config.clientSecret

clientSecret: string

config.enabled

enabled: boolean

config.halfConfigured

halfConfigured: boolean

config.scope

scope: string

config.tokenUrl

tokenUrl: string

consumeState

consumeState: (key, state) => boolean

The state is consumed FIRST and unconditionally: a replayed callback finds nothing, and a state started by another session is spent (not merely refused) the moment it is presented. -> true only for this session's own, unexpired, never-used state.

Parameters
key

any

state

any

Returns

boolean

disconnect

disconnect: (key) => Promise<{ ok: boolean; wasConnected: boolean; }>

Disconnect: zero the token now, and ask the provider to revoke it (best effort, never blocks or fails this).

Parameters
key

any

Returns

Promise<{ ok: boolean; wasConnected: boolean; }>

enabled

enabled: boolean

listRepos

listRepos: (key, __namedParameters) => Promise<any>

The repositories the connection can read: names and visibility only. For a GitHub App the installations the person can use and the repositories of each; for an OAuth app (the installations endpoint refuses its tokens) the person's own repositories. -> { ok:true, repos, page, perPage, total, hasMore, truncated, source } | { ok:false, status, code, error }

Parameters
key

any

__namedParameters?
page?

number = 1

perPage?

number = 30

q?

string = ''

Returns

Promise<any>

status

status: (key) => { connected: boolean; enabled: boolean; login?: undefined; } | { connected: boolean; enabled: boolean; login: any; }

Parameters
key

any

Returns

{ connected: boolean; enabled: boolean; login?: undefined; } | { connected: boolean; enabled: boolean; login: any; }

sweep

sweep: () => void

Returns

void

wipeAll

wipeAll: () => void

Returns

void

wipeKey

wipeKey: (key) => boolean

Parameters
key

any

Returns

boolean

resolveRepoConnectionConfig()#

resolveRepoConnectionConfig(env?, __namedParameters?): object

Defined in: ui/server/src/repoConnection.mjs:57

Resolve the feature's configuration from the environment. CONSTRUCT_GITHUB_REPO_CLIENT_ID / _SECRET both set -> enabled; neither -> off; one only -> off, with a warning. CONSTRUCT_GITHUB_REPO_CALLBACK_URL default: the sign-in callback URL with /auth/callback -> /auth/repo/callback, else http://localhost:/auth/repo/callback CONSTRUCT_GITHUB_REPO_SCOPE optional; only an OAuth app needs it (e.g. repo); a GitHub App ignores it. CONSTRUCT_E2E_GITHUB_REPO_OAUTH_BASE / _API_BASE TEST HARNESS ONLY: a mock standing in for github.com and api.github.com. Refused in production and off loopback (testSeams.mjs, ).

Parameters#

env?

any = process.env

__namedParameters?
host?

string = '127.0.0.1'

port?

number = 4000

Returns#

object

apiBase

apiBase: string

authorizeUrl

authorizeUrl: string

callbackUrl

callbackUrl: string

clientId

clientId: string

clientSecret

clientSecret: string

enabled

enabled: boolean

halfConfigured

halfConfigured: boolean

scope

scope: string

tokenUrl

tokenUrl: string

sessionKeyOf()#

sessionKeyOf(session): string

Defined in: ui/server/src/repoConnection.mjs:46

The key a session's connection is stored under: the signed-in login (lower case), '' with no login (local run).

Parameters#

session

any

Returns#

string