saaslayer 0.4.2 → 0.5.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/bin/saaslayer.js +23 -11
- package/package.json +7 -7
- package/src/cdn-aws.js +67 -0
- package/src/cdn-publication.js +146 -0
- package/src/cdn-publisher.js +166 -0
- package/src/commands/cdn.js +66 -0
- package/src/commands/deploy.js +4 -3
- package/src/commands/lifecycle.js +20 -2
- package/src/commands/operations.js +8 -3
- package/src/commands/stacks.js +2 -0
- package/src/commands/users-management.js +2 -2
- package/src/deployments.js +5 -2
- package/src/module-catalog.js +15 -5
- package/src/sms/scope.js +4 -2
- package/src/source-branch.js +36 -0
- package/src/users-import/ids.js +1 -1
- package/templates/saaslayer-foundation.yml +215 -281
- package/vendor/config/login-domain.js +213 -0
- package/vendor/discovery/index.d.mts +109 -0
- package/vendor/discovery/index.mjs +409 -0
- package/vendor/ids/index.d.ts +21 -0
- package/vendor/ids/index.js +237 -0
- package/vendor/migrations/backups.js +118 -0
- package/vendor/migrations/child.js +78 -0
- package/vendor/migrations/credentials.js +103 -0
- package/vendor/migrations/errors.js +30 -0
- package/vendor/migrations/exec-child.js +78 -0
- package/vendor/migrations/gate.js +51 -0
- package/vendor/migrations/index.js +30 -0
- package/vendor/migrations/inventory.js +92 -0
- package/vendor/migrations/log.js +14 -0
- package/vendor/migrations/release.js +45 -0
- package/vendor/migrations/report.js +129 -0
- package/vendor/migrations/rules.js +104 -0
- package/vendor/migrations/run.js +311 -0
- package/vendor/migrations/session-policy.js +37 -0
- package/vendor/migrations/step-guard.js +82 -0
- package/vendor/operations/activity.d.ts +21 -0
- package/vendor/operations/activity.js +126 -0
- package/vendor/operations/index.d.ts +72 -0
- package/vendor/operations/index.js +510 -0
- package/vendor/permissions-engine-core/account-status.js +270 -0
- package/vendor/permissions-engine-core/delegation.js +174 -0
- package/vendor/permissions-engine-core/direct-mode-contract.js +237 -0
- package/vendor/permissions-engine-core/sso-claims.js +206 -0
- package/vendor/user-management/cognito/emails/token-registry.js +48 -0
- package/vendor/user-management/email/validate.js +207 -0
- package/vendor/user-management/extensibility/hook-contract.js +720 -0
- package/vendor/user-management/extensibility/safe-webhook.js +85 -0
- package/vendor/user-management/identity/admission.js +215 -0
- package/vendor/user-management/identity/attr.js +27 -0
- package/vendor/user-management/identity/attribute-registry.js +115 -0
- package/vendor/user-management/identity/email.js +25 -0
- package/vendor/user-management/identity/ensure-suid.js +74 -0
- package/vendor/user-management/identity/pointers.js +192 -0
- package/vendor/user-management/identity/stitch-provider.js +275 -0
- package/vendor/user-management/management/apply-request.js +227 -0
- package/vendor/user-management/management/core-profile.js +110 -0
- package/vendor/user-management/management/index.js +23 -0
- package/vendor/user-management/management/purposes.js +94 -0
- package/vendor/user-management/management/registry.js +569 -0
- package/vendor/user-management/store/table.js +332 -0
|
@@ -0,0 +1,510 @@
|
|
|
1
|
+
// The operation resource shared by the control plane, deployed services, CLI and console: durable id, kind,
|
|
2
|
+
// status (pending|running|succeeded|failed|partial), per-component outcomes, idempotency, redaction and watch.
|
|
3
|
+
'use strict'
|
|
4
|
+
|
|
5
|
+
/** @typedef {'pending'|'running'|'succeeded'|'failed'|'partial'|'superseded'} OperationStatus */
|
|
6
|
+
/** @typedef {'pending'|'running'|'succeeded'|'failed'|'skipped'|'unknown'} ComponentStatus */
|
|
7
|
+
/** @typedef {{ code?: string|null, message?: string|null }} OperationError */
|
|
8
|
+
/**
|
|
9
|
+
* @typedef {object} OperationComponent
|
|
10
|
+
* @property {string} name
|
|
11
|
+
* @property {ComponentStatus} status
|
|
12
|
+
* @property {'external'} [delivery] an external delivery (email, webhook) whose outcome may stay unknown
|
|
13
|
+
* @property {OperationError} [error]
|
|
14
|
+
* @property {string} [nextAction] the next supported command for this component
|
|
15
|
+
* @property {Record<string, unknown>} [detail] the component's own reported state (redacted), e.g. a bootstrap's step
|
|
16
|
+
* @property {FunctionCode} [functionCode] after a code-only update stopped partway: which functions run which code
|
|
17
|
+
* @property {Strategy} [strategy] how the deployment plan chose to apply this component
|
|
18
|
+
* @property {string} [strategyReason] why the plan chose that strategy (redacted)
|
|
19
|
+
*/
|
|
20
|
+
/** @typedef {'unchanged'|'fullDeploy'|'codeDeploy'} Strategy */
|
|
21
|
+
/**
|
|
22
|
+
* @typedef {object} FunctionCode
|
|
23
|
+
* @property {string[]} updated functions running the requested code
|
|
24
|
+
* @property {string[]} old functions provably still running the previous code
|
|
25
|
+
* @property {string[]} unknown functions whose code could not be determined
|
|
26
|
+
*/
|
|
27
|
+
/**
|
|
28
|
+
* @typedef {object} Operation
|
|
29
|
+
* @property {string} id
|
|
30
|
+
* @property {string} kind
|
|
31
|
+
* @property {OperationStatus} status
|
|
32
|
+
* @property {OperationComponent[]} components
|
|
33
|
+
* @property {string|null} createdAt
|
|
34
|
+
* @property {string|null} updatedAt
|
|
35
|
+
* @property {string|null} requestKey
|
|
36
|
+
* @property {string} [deploymentId]
|
|
37
|
+
* @property {OperationError} [error]
|
|
38
|
+
* @property {string} [nextAction]
|
|
39
|
+
* @property {Record<string, unknown>} [purgeResult] a delete destroy's or purge's report: complete, pending or incomplete
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
const OPERATION_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'partial', 'superseded']
|
|
43
|
+
const COMPONENT_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'skipped', 'unknown']
|
|
44
|
+
/** The plan strategies a component reports; any other planned value is left out. */
|
|
45
|
+
const STRATEGIES = ['unchanged', 'fullDeploy', 'codeDeploy']
|
|
46
|
+
const EXTERNAL_DELIVERY_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'unknown']
|
|
47
|
+
// superseded: a waiting request replaced by a newer one before it started; it never ran
|
|
48
|
+
const TERMINAL_STATUSES = ['succeeded', 'failed', 'partial', 'superseded']
|
|
49
|
+
|
|
50
|
+
// How long a request key (and the operation it names) is replayable: 7 days. After that the key may be reused.
|
|
51
|
+
const IDEMPOTENCY_RETENTION_SECONDS = 7 * 24 * 60 * 60
|
|
52
|
+
|
|
53
|
+
/** @type {Record<string, OperationStatus[]>} */
|
|
54
|
+
const ALLOWED_TRANSITIONS = {
|
|
55
|
+
pending: ['running', 'succeeded', 'failed', 'partial', 'superseded'],
|
|
56
|
+
running: ['succeeded', 'failed', 'partial'],
|
|
57
|
+
succeeded: [],
|
|
58
|
+
failed: [],
|
|
59
|
+
partial: [],
|
|
60
|
+
superseded: [],
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** @param {string} status */
|
|
64
|
+
function isTerminal(status) {
|
|
65
|
+
return TERMINAL_STATUSES.includes(status)
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* @param {{ id: string, kind: string, requestKey?: string|null, components?: Array<string|{ name: string, delivery?: 'external' }>, now: string }} input
|
|
70
|
+
* @returns {Operation}
|
|
71
|
+
*/
|
|
72
|
+
function createOperation({ id, kind, requestKey = null, components = [], now }) {
|
|
73
|
+
if (!id || !kind) throw new Error('createOperation: id and kind are required')
|
|
74
|
+
return {
|
|
75
|
+
id,
|
|
76
|
+
kind,
|
|
77
|
+
status: 'pending',
|
|
78
|
+
components: components.map((c) => {
|
|
79
|
+
const spec = typeof c === 'string' ? { name: c } : c
|
|
80
|
+
return { name: spec.name, status: 'pending', ...(spec.delivery === 'external' ? { delivery: 'external' } : {}) }
|
|
81
|
+
}),
|
|
82
|
+
createdAt: now,
|
|
83
|
+
updatedAt: now,
|
|
84
|
+
requestKey,
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Move an operation to a new status. Same-state is a no-op; leaving a terminal state throws.
|
|
90
|
+
* @param {Operation} op
|
|
91
|
+
* @param {string} next
|
|
92
|
+
* @param {string} now
|
|
93
|
+
* @returns {Operation}
|
|
94
|
+
*/
|
|
95
|
+
function transition(op, next, now) {
|
|
96
|
+
if (!OPERATION_STATUSES.includes(next)) throw new Error(`unknown operation status "${next}"`)
|
|
97
|
+
if (op.status === next) return op
|
|
98
|
+
if (!ALLOWED_TRANSITIONS[op.status].includes(/** @type {OperationStatus} */ (next))) {
|
|
99
|
+
throw new Error(`illegal operation transition ${op.status} -> ${next}`)
|
|
100
|
+
}
|
|
101
|
+
return { ...op, status: /** @type {OperationStatus} */ (next), updatedAt: now }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* The operation status implied by its components: all pending = pending; any pending/running = running; else
|
|
106
|
+
* no failure = succeeded (an external delivery's unknown is not a failure), failures plus successes = partial,
|
|
107
|
+
* only failures = failed.
|
|
108
|
+
* @param {OperationComponent[]} components
|
|
109
|
+
* @returns {OperationStatus}
|
|
110
|
+
*/
|
|
111
|
+
function rollupStatus(components) {
|
|
112
|
+
if (components.length === 0) return 'pending'
|
|
113
|
+
if (components.every((c) => c.status === 'pending')) return 'pending'
|
|
114
|
+
if (components.some((c) => c.status === 'pending' || c.status === 'running')) return 'running'
|
|
115
|
+
const failed = components.filter((c) => c.status === 'failed').length
|
|
116
|
+
if (failed === 0) return 'succeeded'
|
|
117
|
+
return components.some((c) => c.status === 'succeeded' || c.status === 'unknown') ? 'partial' : 'failed'
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Record one component's outcome and roll the operation status up from its components.
|
|
122
|
+
* @param {Operation} op
|
|
123
|
+
* @param {string} name
|
|
124
|
+
* @param {{ status: string, error?: OperationError, nextAction?: string }} patch
|
|
125
|
+
* @param {string} now
|
|
126
|
+
* @returns {Operation}
|
|
127
|
+
*/
|
|
128
|
+
function updateComponent(op, name, patch, now) {
|
|
129
|
+
const index = op.components.findIndex((c) => c.name === name)
|
|
130
|
+
if (index < 0) throw new Error(`no component "${name}" on operation ${op.id}`)
|
|
131
|
+
if (!COMPONENT_STATUSES.includes(patch.status)) throw new Error(`unknown component status "${patch.status}"`)
|
|
132
|
+
const current = op.components[index]
|
|
133
|
+
if (current.delivery === 'external' && !EXTERNAL_DELIVERY_STATUSES.includes(patch.status)) {
|
|
134
|
+
throw new Error(`external delivery component "${name}" reports succeeded|failed|unknown`)
|
|
135
|
+
}
|
|
136
|
+
const component = {
|
|
137
|
+
...current,
|
|
138
|
+
status: /** @type {ComponentStatus} */ (patch.status),
|
|
139
|
+
...(patch.error ? { error: redact(patch.error) } : {}),
|
|
140
|
+
...(patch.nextAction ? { nextAction: patch.nextAction } : {}),
|
|
141
|
+
}
|
|
142
|
+
const components = op.components.map((c, i) => (i === index ? component : c))
|
|
143
|
+
return transition({ ...op, components, updatedAt: now }, rollupStatus(components), now)
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// ---- Idempotency -------------------------------------------------------------------------------------
|
|
147
|
+
|
|
148
|
+
/** @param {unknown} value @returns {unknown} */
|
|
149
|
+
function canonical(value) {
|
|
150
|
+
if (Array.isArray(value)) return value.map(canonical)
|
|
151
|
+
if (value && typeof value === 'object') {
|
|
152
|
+
return Object.keys(value).sort().reduce((acc, key) => {
|
|
153
|
+
acc[key] = canonical(/** @type {Record<string, unknown>} */ (value)[key])
|
|
154
|
+
return acc
|
|
155
|
+
}, /** @type {Record<string, unknown>} */ ({}))
|
|
156
|
+
}
|
|
157
|
+
return value
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* The payload fingerprint a request key is bound to (sha256 of the key-sorted JSON).
|
|
162
|
+
* @param {unknown} payload
|
|
163
|
+
*/
|
|
164
|
+
function fingerprint(payload) {
|
|
165
|
+
// Required here, not at module load: browser bundles import this module for redaction and rendering only.
|
|
166
|
+
const { createHash } = require('node:crypto')
|
|
167
|
+
return createHash('sha256').update(JSON.stringify(canonical(payload === undefined ? null : payload))).digest('hex')
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* A request key scoped by its scope (a deployment id) and operation kind, so one key can't collide across them.
|
|
172
|
+
* @param {{ scope: string, kind: string, requestKey: string }} input
|
|
173
|
+
*/
|
|
174
|
+
function idempotencyScopeKey({ scope, kind, requestKey }) {
|
|
175
|
+
if (!scope || !kind || !requestKey) throw new Error('idempotencyScopeKey: scope, kind and requestKey are required')
|
|
176
|
+
return `${scope}#${kind}#${requestKey}`
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* The DynamoDB ttl (epoch seconds) for a request key recorded at nowMs.
|
|
181
|
+
* @param {number} nowMs
|
|
182
|
+
*/
|
|
183
|
+
function idempotencyExpiry(nowMs) {
|
|
184
|
+
return Math.floor(nowMs / 1000) + IDEMPOTENCY_RETENTION_SECONDS
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Decide what a request with this key + payload does against the stored key record: 'new' (no live record),
|
|
189
|
+
* 'replay' (same payload — return the same operation) or 'conflict' (different payload — 409). A record past
|
|
190
|
+
* its ttl (or, without one, past createdAt + retention) is expired and treated as absent.
|
|
191
|
+
* @param {{ record: { requestHash?: unknown, runId?: unknown, operationId?: unknown, ttl?: unknown, createdAt?: unknown } | null | undefined, fingerprint: string, nowMs: number }} input
|
|
192
|
+
* @returns {{ action: 'new' } | { action: 'replay', operationId: string|null } | { action: 'conflict', statusCode: 409, code: 'IDEMPOTENCY_KEY_REUSED', error: string }}
|
|
193
|
+
*/
|
|
194
|
+
function resolveIdempotency({ record, fingerprint: requestFingerprint, nowMs }) {
|
|
195
|
+
if (!record) return { action: 'new' }
|
|
196
|
+
const expiresAtSeconds = typeof record.ttl === 'number'
|
|
197
|
+
? record.ttl
|
|
198
|
+
: typeof record.createdAt === 'string' ? Math.floor(Date.parse(record.createdAt) / 1000) + IDEMPOTENCY_RETENTION_SECONDS : null
|
|
199
|
+
if (expiresAtSeconds !== null && expiresAtSeconds * 1000 < nowMs) return { action: 'new' }
|
|
200
|
+
if (record.requestHash !== requestFingerprint) {
|
|
201
|
+
return { action: 'conflict', statusCode: 409, code: 'IDEMPOTENCY_KEY_REUSED', error: 'Idempotency-Key was already used with a different request body' }
|
|
202
|
+
}
|
|
203
|
+
const operationId = record.operationId || record.runId
|
|
204
|
+
return { action: 'replay', operationId: typeof operationId === 'string' ? operationId : null }
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
// ---- Deployer runs as operations ---------------------------------------------------------------------
|
|
208
|
+
|
|
209
|
+
/** @type {Record<string, string>} */
|
|
210
|
+
const KIND_BY_RUN_TYPE = {
|
|
211
|
+
CREATE: 'deployment.create',
|
|
212
|
+
UPDATE: 'deployment.update',
|
|
213
|
+
DESTROY: 'deployment.destroy',
|
|
214
|
+
PURGE: 'deployment.purge',
|
|
215
|
+
MIGRATE: 'deployment.migrate',
|
|
216
|
+
ADD_SERVICE: 'service.add',
|
|
217
|
+
REMOVE_SERVICE: 'service.remove',
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** @param {unknown} customDomain the custom domain a run carries @returns {string|null} its operation kind */
|
|
221
|
+
function customDomainKind(customDomain) {
|
|
222
|
+
const action = customDomain && typeof customDomain === 'object' ? /** @type {{ action?: unknown }} */ (customDomain).action : null
|
|
223
|
+
return action === 'attach' || action === 'remove' ? `service.custom-domain.${action}` : null
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
// The login-domain actions a dedicated UPDATE run carries (run.loginDomain.action): kind service.login-domain.<action>.
|
|
227
|
+
const LOGIN_DOMAIN_ACTIONS = ['provision', 'activate', 'deactivate', 'remove']
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* The login-domain action a run was started for, or null.
|
|
231
|
+
* @param {Record<string, unknown>} run
|
|
232
|
+
* @returns {string|null}
|
|
233
|
+
*/
|
|
234
|
+
function loginDomainAction(run) {
|
|
235
|
+
const action = run.loginDomain && typeof run.loginDomain === 'object' ? /** @type {{ action?: unknown }} */ (run.loginDomain).action : null
|
|
236
|
+
return typeof action === 'string' && LOGIN_DOMAIN_ACTIONS.includes(action) ? action : null
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* A module result's per-function code report, or undefined when absent or malformed.
|
|
241
|
+
* @param {unknown} value
|
|
242
|
+
* @returns {FunctionCode|undefined}
|
|
243
|
+
*/
|
|
244
|
+
function functionCodeOf(value) {
|
|
245
|
+
if (!value || typeof value !== 'object') return undefined
|
|
246
|
+
const v = /** @type {Record<string, unknown>} */ (value)
|
|
247
|
+
const names = (/** @type {unknown} */ x) => Array.isArray(x) && x.every((n) => typeof n === 'string')
|
|
248
|
+
if (!names(v.updated) || !names(v.old) || !names(v.unknown)) return undefined
|
|
249
|
+
return { updated: [.../** @type {string[]} */ (v.updated)], old: [.../** @type {string[]} */ (v.old)], unknown: [.../** @type {string[]} */ (v.unknown)] }
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** @param {string|null|undefined} runStatus @returns {OperationStatus} */
|
|
253
|
+
function statusFromRun(runStatus) {
|
|
254
|
+
if (runStatus === 'QUEUED' || runStatus === 'WAITING') return 'pending'
|
|
255
|
+
if (runStatus === 'RUNNING' || runStatus === 'CANCEL_REQUESTED') return 'running'
|
|
256
|
+
if (runStatus === 'SUCCEEDED') return 'succeeded'
|
|
257
|
+
if (runStatus === 'SUPERSEDED') return 'superseded'
|
|
258
|
+
return 'failed'
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* The CLI command that retries (or, for a blocked/non-retryable failure, inspects) a failed run.
|
|
263
|
+
* @param {{ kind: string, deploymentId?: string, run: Record<string, unknown>, service?: string, retryable?: unknown, blocked?: unknown }} input
|
|
264
|
+
*/
|
|
265
|
+
function nextActionFor({ kind, deploymentId, run, service, retryable, blocked }) {
|
|
266
|
+
if (blocked === true || retryable === false) return 'saaslayer status'
|
|
267
|
+
switch (kind) {
|
|
268
|
+
case 'deployment.create': return 'saaslayer deploy'
|
|
269
|
+
case 'deployment.update': return run.targetCommitSha ? `saaslayer update --commit-sha ${run.targetCommitSha}` : 'saaslayer update'
|
|
270
|
+
case 'deployment.destroy': return 'saaslayer destroy --data-custody delete|retain'
|
|
271
|
+
case 'deployment.purge': return 'saaslayer destroy --purge-retained --reason TEXT'
|
|
272
|
+
case 'deployment.migrate': return `saaslayer migrate status --deployment ${deploymentId}`
|
|
273
|
+
case 'service.add': return `saaslayer service add ${service}`
|
|
274
|
+
case 'service.remove': return `saaslayer service remove ${service} --data-custody delete|retain`
|
|
275
|
+
default:
|
|
276
|
+
// A login-domain run's state (and the next step) is read back with status, whichever action failed.
|
|
277
|
+
if (kind.startsWith('service.login-domain.')) return `saaslayer login-domain status --service ${service}`
|
|
278
|
+
return 'saaslayer status'
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/** @param {Record<string, unknown>} result @returns {ComponentStatus|null} */
|
|
283
|
+
function componentStatusFromResult(result) {
|
|
284
|
+
// A component a step reports itself (a seed's first-admin bootstrap) carries its own status.
|
|
285
|
+
if (typeof result.componentStatus === 'string' && COMPONENT_STATUSES.includes(result.componentStatus)) return /** @type {ComponentStatus} */ (result.componentStatus)
|
|
286
|
+
const outcomes = [result.deployStatus, result.removeStatus]
|
|
287
|
+
if (outcomes.includes('FAILED')) return 'failed'
|
|
288
|
+
if (outcomes.includes('SUCCEEDED')) return 'succeeded'
|
|
289
|
+
if (outcomes.includes('SKIPPED')) return 'skipped'
|
|
290
|
+
return null
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/** @param {unknown} code @param {unknown} message @returns {OperationError|undefined} */
|
|
294
|
+
function errorOf(code, message) {
|
|
295
|
+
if (!code && !message) return undefined
|
|
296
|
+
return { code: typeof code === 'string' ? code : null, message: typeof message === 'string' ? redactText(message) : null }
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/** @param {unknown} v @returns {string[]} */
|
|
300
|
+
function strList(v) {
|
|
301
|
+
return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Project a deployer run (and its per-module results) as an operation. The run id IS the operation id.
|
|
306
|
+
* @param {{ deploymentId?: string, run: Record<string, unknown>, moduleResults?: Array<Record<string, unknown>> }} input
|
|
307
|
+
* @returns {Operation}
|
|
308
|
+
*/
|
|
309
|
+
function operationFromRun({ deploymentId, run, moduleResults = [] }) {
|
|
310
|
+
// A run started for an explicit first-admin request (deployer action admin-bootstrap) is that operation; so is a run
|
|
311
|
+
// started to attach or remove a custom domain.
|
|
312
|
+
const kind = run.adminBootstrap ? 'deployment.admin-bootstrap'
|
|
313
|
+
: loginDomainAction(run) ? `service.login-domain.${loginDomainAction(run)}`
|
|
314
|
+
: customDomainKind(run.customDomain) || KIND_BY_RUN_TYPE[String(run.type)] || `deployment.${String(run.type || 'run').toLowerCase()}`
|
|
315
|
+
const runStatus = statusFromRun(/** @type {string|undefined} */ (run.status))
|
|
316
|
+
const requested = strList(run.requestedServices).length ? strList(run.requestedServices) : strList(run.requestedModules)
|
|
317
|
+
const loginDomainService = loginDomainAction(run) ? String(/** @type {{ service?: unknown }} */ (run.loginDomain).service || '') : ''
|
|
318
|
+
const resultByName = new Map(moduleResults.filter((r) => typeof r.moduleName === 'string').map((r) => [String(r.moduleName), r]))
|
|
319
|
+
const names = [...requested, ...[...resultByName.keys()].filter((n) => !requested.includes(n))]
|
|
320
|
+
/** @type {OperationComponent[]} */
|
|
321
|
+
const components = names.map((name) => {
|
|
322
|
+
const result = resultByName.get(name)
|
|
323
|
+
const reported = result ? componentStatusFromResult(result) : null
|
|
324
|
+
/** @type {ComponentStatus} */
|
|
325
|
+
const status = reported || (runStatus === 'succeeded' ? 'succeeded' : runStatus === 'failed' ? 'unknown' : runStatus === 'superseded' ? 'skipped' : 'pending')
|
|
326
|
+
/** @type {OperationComponent} */
|
|
327
|
+
const component = { name: result && typeof result.component === 'string' ? result.component : name, status }
|
|
328
|
+
const error = result ? errorOf(result.errorCode, result.errorMessage) : undefined
|
|
329
|
+
if (error) component.error = error
|
|
330
|
+
if (result && result.detail && typeof result.detail === 'object' && !Array.isArray(result.detail)) {
|
|
331
|
+
component.detail = /** @type {Record<string, unknown>} */ (redact(result.detail))
|
|
332
|
+
}
|
|
333
|
+
const functionCode = result ? functionCodeOf(result.functionCode) : undefined
|
|
334
|
+
if (functionCode) component.functionCode = functionCode
|
|
335
|
+
if (result && typeof result.strategy === 'string' && STRATEGIES.includes(result.strategy)) {
|
|
336
|
+
component.strategy = /** @type {Strategy} */ (result.strategy)
|
|
337
|
+
if (typeof result.strategyReason === 'string' && result.strategyReason) component.strategyReason = redactText(result.strategyReason)
|
|
338
|
+
}
|
|
339
|
+
if (status === 'failed') {
|
|
340
|
+
component.nextAction = nextActionFor({ kind, deploymentId, run, service: name, retryable: result && result.retryable !== undefined ? result.retryable : run.retryable, blocked: run.blocked })
|
|
341
|
+
}
|
|
342
|
+
return component
|
|
343
|
+
})
|
|
344
|
+
const anySucceeded = components.some((c) => c.status === 'succeeded')
|
|
345
|
+
const anyFailed = components.some((c) => c.status === 'failed')
|
|
346
|
+
/** @type {OperationStatus} */
|
|
347
|
+
const status = (runStatus === 'failed' && anySucceeded) || (runStatus === 'succeeded' && anyFailed) ? 'partial' : runStatus
|
|
348
|
+
/** @type {Operation} */
|
|
349
|
+
const op = {
|
|
350
|
+
id: String(run.runId),
|
|
351
|
+
kind,
|
|
352
|
+
status,
|
|
353
|
+
components,
|
|
354
|
+
createdAt: typeof run.createdAt === 'string' ? run.createdAt : null,
|
|
355
|
+
updatedAt: typeof run.updatedAt === 'string' ? run.updatedAt : null,
|
|
356
|
+
requestKey: typeof run.idempotencyKey === 'string' ? run.idempotencyKey : typeof run.requestKey === 'string' ? run.requestKey : null,
|
|
357
|
+
}
|
|
358
|
+
if (deploymentId) op.deploymentId = deploymentId
|
|
359
|
+
// A delete destroy or a purge reports what it removed and what remains (ADR 0006 §5 purgeResult).
|
|
360
|
+
if (run.purgeResult && typeof run.purgeResult === 'object') op.purgeResult = /** @type {Record<string, unknown>} */ (run.purgeResult)
|
|
361
|
+
const error = errorOf(run.errorCode, run.errorMessage)
|
|
362
|
+
if (error) op.error = error
|
|
363
|
+
if (status === 'failed' || status === 'partial') {
|
|
364
|
+
op.nextAction = nextActionFor({ kind, deploymentId, run, service: loginDomainService || requested[0] || names[0], retryable: run.retryable, blocked: run.blocked })
|
|
365
|
+
}
|
|
366
|
+
return op
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* A simple synchronous write's response: the result, the request id and the resource's revision (no operation).
|
|
371
|
+
* @param {{ result: unknown, requestId: string, revision: number|string }} input
|
|
372
|
+
*/
|
|
373
|
+
function syncWriteResult({ result, requestId, revision }) {
|
|
374
|
+
if (!requestId) throw new Error('syncWriteResult: requestId is required')
|
|
375
|
+
return { result: redact(result), requestId, revision }
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
// ---- Redaction ---------------------------------------------------------------------------------------
|
|
379
|
+
|
|
380
|
+
const REDACTED = '[REDACTED]'
|
|
381
|
+
const SECRET_KEY_RE = /pass(word|code)?$|secret|token|authorization|api[-_]?key|invitation|credential/i
|
|
382
|
+
const SECRET_NAMES = 'password|passcode|secret|clientSecret|token|idToken|accessToken|refreshToken|invitationToken|apiKey|api_key'
|
|
383
|
+
|
|
384
|
+
/**
|
|
385
|
+
* Remove bearer tokens, JWTs and `name=value` / `"name":"value"` secrets from free text.
|
|
386
|
+
* @param {string} text
|
|
387
|
+
*/
|
|
388
|
+
function redactText(text) {
|
|
389
|
+
return String(text)
|
|
390
|
+
.replace(/Bearer\s+[^\s"',]+/gi, `Bearer ${REDACTED}`)
|
|
391
|
+
.replace(/eyJ[\w-]+\.[\w-]+\.[\w-]+/g, REDACTED)
|
|
392
|
+
.replace(new RegExp(`"(${SECRET_NAMES})"\\s*:\\s*"[^"]*"`, 'gi'), `"$1":"${REDACTED}"`)
|
|
393
|
+
.replace(new RegExp(`\\b(${SECRET_NAMES})=([^\\s&"',]+)`, 'gi'), `$1=${REDACTED}`)
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
/**
|
|
397
|
+
* Deep-copy a value with secret-named fields replaced and free-text secrets removed from strings.
|
|
398
|
+
* @template T
|
|
399
|
+
* @param {T} value
|
|
400
|
+
* @returns {T}
|
|
401
|
+
*/
|
|
402
|
+
function redact(value) {
|
|
403
|
+
if (typeof value === 'string') return /** @type {T} */ (/** @type {unknown} */ (redactText(value)))
|
|
404
|
+
if (Array.isArray(value)) return /** @type {T} */ (/** @type {unknown} */ (value.map(redact)))
|
|
405
|
+
if (value && typeof value === 'object') {
|
|
406
|
+
/** @type {Record<string, unknown>} */
|
|
407
|
+
const out = {}
|
|
408
|
+
for (const [key, v] of Object.entries(value)) out[key] = SECRET_KEY_RE.test(key) && v != null ? REDACTED : redact(v)
|
|
409
|
+
return /** @type {T} */ (/** @type {unknown} */ (out))
|
|
410
|
+
}
|
|
411
|
+
return value
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
// ---- Logs + rendering --------------------------------------------------------------------------------
|
|
415
|
+
|
|
416
|
+
/**
|
|
417
|
+
* The structured log line for an operation (optionally focused on one component): operation {id, kind, status, component}.
|
|
418
|
+
* @param {Operation} op
|
|
419
|
+
* @param {string} [componentName]
|
|
420
|
+
*/
|
|
421
|
+
function operationLogLine(op, componentName) {
|
|
422
|
+
/** @type {Record<string, unknown>} */
|
|
423
|
+
const line = { event: 'operation', id: op.id, kind: op.kind, status: op.status }
|
|
424
|
+
if (componentName) {
|
|
425
|
+
const c = op.components.find((x) => x.name === componentName)
|
|
426
|
+
if (c) line.component = { name: c.name, status: c.status, ...(c.error && c.error.code ? { errorCode: c.error.code } : {}) }
|
|
427
|
+
}
|
|
428
|
+
return redactText(JSON.stringify(line))
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
/**
|
|
432
|
+
* Human-readable lines for an operation — the one rendering the CLI and console share.
|
|
433
|
+
* @param {Operation} op
|
|
434
|
+
* @returns {string[]}
|
|
435
|
+
*/
|
|
436
|
+
function formatOperation(op) {
|
|
437
|
+
const lines = [`operation ${op.id} (${op.kind}): ${op.status}`]
|
|
438
|
+
const width = Math.max(0, ...op.components.map((c) => c.name.length))
|
|
439
|
+
for (const c of op.components) {
|
|
440
|
+
const err = c.error ? ` ${[c.error.code, c.error.message].filter(Boolean).join(': ')}` : ''
|
|
441
|
+
const strategy = c.strategy ? ` ${[c.strategy, c.strategyReason].filter(Boolean).join(': ')}` : ''
|
|
442
|
+
lines.push(` ${c.name.padEnd(width)} ${c.status}${strategy}${err}`)
|
|
443
|
+
if (c.functionCode) {
|
|
444
|
+
const list = (/** @type {string[]} */ xs) => (xs.length ? xs.join(', ') : 'none')
|
|
445
|
+
lines.push(` ${''.padEnd(width)} functions updated: ${list(c.functionCode.updated)}; old: ${list(c.functionCode.old)}; unknown: ${list(c.functionCode.unknown)}`)
|
|
446
|
+
}
|
|
447
|
+
}
|
|
448
|
+
if (op.error && !op.components.some((c) => c.error)) lines.push(` error: ${[op.error.code, op.error.message].filter(Boolean).join(': ')}`)
|
|
449
|
+
const next = [...new Set([op.nextAction, ...op.components.map((c) => c.nextAction)].filter(Boolean))]
|
|
450
|
+
for (const n of next) lines.push(` next: ${n}`)
|
|
451
|
+
return lines
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/**
|
|
455
|
+
* Poll an operation until it is terminal. Transient fetch errors (a dropped connection) are retried; after
|
|
456
|
+
* maxConsecutiveErrors in a row it gives up with an OPERATION_CONNECTION_LOST error naming the resume command. An
|
|
457
|
+
* error marked `fatal` (a 4xx such as a missing operation) is rethrown at once.
|
|
458
|
+
* @param {{ id: string, fetchOperation: () => Promise<Operation>, sleep?: (ms: number) => Promise<void>, intervalMs?: number, maxConsecutiveErrors?: number, onUpdate?: (op: Operation) => void, resumeCommand?: string }} input
|
|
459
|
+
* @returns {Promise<Operation>}
|
|
460
|
+
*/
|
|
461
|
+
async function watchOperation({ id, fetchOperation, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), intervalMs = 5000, maxConsecutiveErrors = 5, onUpdate, resumeCommand }) {
|
|
462
|
+
let errors = 0
|
|
463
|
+
let lastSignature = ''
|
|
464
|
+
for (;;) {
|
|
465
|
+
try {
|
|
466
|
+
const op = await fetchOperation()
|
|
467
|
+
errors = 0
|
|
468
|
+
const signature = JSON.stringify([op.status, op.components])
|
|
469
|
+
if (signature !== lastSignature) {
|
|
470
|
+
lastSignature = signature
|
|
471
|
+
if (onUpdate) onUpdate(op)
|
|
472
|
+
}
|
|
473
|
+
if (isTerminal(op.status)) return op
|
|
474
|
+
} catch (err) {
|
|
475
|
+
if (err && /** @type {{ fatal?: boolean }} */ (err).fatal) throw err
|
|
476
|
+
errors++
|
|
477
|
+
if (errors >= maxConsecutiveErrors) {
|
|
478
|
+
const reason = err && /** @type {Error} */ (err).message ? /** @type {Error} */ (err).message : String(err)
|
|
479
|
+
const lost = /** @type {Error & { code?: string, operationId?: string }} */ (new Error(`lost connection while watching operation ${id} (${redactText(reason)})${resumeCommand ? ` — resume with: ${resumeCommand}` : ''}`))
|
|
480
|
+
lost.code = 'OPERATION_CONNECTION_LOST'
|
|
481
|
+
lost.operationId = id
|
|
482
|
+
throw lost
|
|
483
|
+
}
|
|
484
|
+
}
|
|
485
|
+
await sleep(intervalMs)
|
|
486
|
+
}
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
module.exports = {
|
|
490
|
+
OPERATION_STATUSES,
|
|
491
|
+
COMPONENT_STATUSES,
|
|
492
|
+
TERMINAL_STATUSES,
|
|
493
|
+
IDEMPOTENCY_RETENTION_SECONDS,
|
|
494
|
+
isTerminal,
|
|
495
|
+
createOperation,
|
|
496
|
+
transition,
|
|
497
|
+
rollupStatus,
|
|
498
|
+
updateComponent,
|
|
499
|
+
fingerprint,
|
|
500
|
+
idempotencyScopeKey,
|
|
501
|
+
idempotencyExpiry,
|
|
502
|
+
resolveIdempotency,
|
|
503
|
+
operationFromRun,
|
|
504
|
+
syncWriteResult,
|
|
505
|
+
redact,
|
|
506
|
+
redactText,
|
|
507
|
+
operationLogLine,
|
|
508
|
+
formatOperation,
|
|
509
|
+
watchOperation,
|
|
510
|
+
}
|