saaslayer 0.4.2 → 0.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +5 -6
- package/src/commands/operations.js +1 -1
- package/src/commands/users-management.js +2 -2
- package/src/users-import/ids.js +1 -1
- 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 +60 -0
- package/vendor/operations/index.js +471 -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,129 @@
|
|
|
1
|
+
// Builds the §2.17.6 report-up payload: an idempotent projection of the service ledger (authoritative)
|
|
2
|
+
// plus dry-run, gate and backup facts. Counts and ids only, never item data.
|
|
3
|
+
const { classifyDryRunFailure } = require('./step-guard')
|
|
4
|
+
|
|
5
|
+
const RUN_BLOCK_STATUSES = ['MIGRATION_LOCKED', 'MIGRATION_TOO_LARGE', 'BLOCKED_NO_BACKUP']
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* @typedef {{ status: string, durationMs?: number, progress?: Record<string, any>, sdkStats?: Record<string, any>, error?: string }} StepResult
|
|
9
|
+
* @typedef {{ status: string, checksum?: string, appliedAt?: string, errorMessage?: string }} LedgerRow
|
|
10
|
+
* @typedef {{ status: string, restorePoints: Record<string, string>, backupArns: string[] }} BackupFacts
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/** @param {unknown} v */
|
|
14
|
+
function num(v) {
|
|
15
|
+
return typeof v === 'number' && Number.isFinite(v) ? v : 0
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @param {string} message
|
|
20
|
+
* @param {boolean} dryRun
|
|
21
|
+
*/
|
|
22
|
+
function errorFromMessage(message, dryRun) {
|
|
23
|
+
const prefixed = /^([A-Z][A-Z0-9_]+): /.exec(message)
|
|
24
|
+
const code = dryRun ? classifyDryRunFailure(message) : 'MIGRATION_FAILED'
|
|
25
|
+
return { code: code === 'MIGRATION_FAILED' && prefixed ? prefixed[1] : code, message }
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* @param {LedgerRow|undefined} row
|
|
30
|
+
* @param {StepResult|undefined} dry
|
|
31
|
+
* @param {boolean} waiting
|
|
32
|
+
*/
|
|
33
|
+
function migrationStatus(row, dry, waiting) {
|
|
34
|
+
if (row && row.status === 'completed') return 'completed'
|
|
35
|
+
// This run's gate holds the migration: a failed or interrupted row from an earlier run is retried only after approval.
|
|
36
|
+
if (waiting) return 'awaiting-approval'
|
|
37
|
+
if (row) {
|
|
38
|
+
if (row.status === 'failed') return 'failed'
|
|
39
|
+
return 'interrupted'
|
|
40
|
+
}
|
|
41
|
+
if (dry && dry.status === 'failed') return 'failed'
|
|
42
|
+
if (dry && dry.status === 'interrupted') return 'interrupted'
|
|
43
|
+
if (dry && dry.status === 'dry-run') return 'dry-run-ok'
|
|
44
|
+
return 'pending'
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* @param {{
|
|
49
|
+
* serviceRef: string, deploymentId?: string|null, commitSha?: string|null, source: string, runId: string,
|
|
50
|
+
* phase: string, mode: string, startedAt: string, finishedAt: string,
|
|
51
|
+
* ledger: { tableName: string, scope: string, stage: string },
|
|
52
|
+
* lock?: { owner: string, takeover: boolean }|null,
|
|
53
|
+
* migrations: { id: string, checksum: string, meta: Record<string, any> }[],
|
|
54
|
+
* ledgerRows?: Record<string, LedgerRow>, dryRun?: Record<string, StepResult>, apply?: Record<string, StepResult>,
|
|
55
|
+
* backups?: Record<string, BackupFacts>, waiting?: string[], approval?: object|null,
|
|
56
|
+
* error?: { code: string, message: string }|null,
|
|
57
|
+
* }} p
|
|
58
|
+
*/
|
|
59
|
+
function buildReport(p) {
|
|
60
|
+
const ledgerRows = p.ledgerRows || {}
|
|
61
|
+
const dryRun = p.dryRun || {}
|
|
62
|
+
const apply = p.apply || {}
|
|
63
|
+
const backups = p.backups || {}
|
|
64
|
+
const waiting = new Set(p.waiting || [])
|
|
65
|
+
|
|
66
|
+
const migrations = p.migrations.map((m) => {
|
|
67
|
+
const row = ledgerRows[m.id]
|
|
68
|
+
const dry = dryRun[m.id]
|
|
69
|
+
const applied = apply[m.id]
|
|
70
|
+
const status = migrationStatus(row, dry, waiting.has(m.id))
|
|
71
|
+
const dryProgress = (dry && dry.progress) || {}
|
|
72
|
+
const applyProgress = (applied && applied.progress) || {}
|
|
73
|
+
let error = null
|
|
74
|
+
if (status === 'failed' || status === 'interrupted') {
|
|
75
|
+
if (row && row.errorMessage) error = errorFromMessage(row.errorMessage, false)
|
|
76
|
+
else if (applied && applied.error) error = errorFromMessage(applied.error, false)
|
|
77
|
+
else if (dry && dry.error) error = errorFromMessage(dry.error, true)
|
|
78
|
+
}
|
|
79
|
+
const facts = backups[m.id]
|
|
80
|
+
return {
|
|
81
|
+
id: m.id,
|
|
82
|
+
checksum: m.checksum,
|
|
83
|
+
phase: m.meta.phase,
|
|
84
|
+
destructive: !!m.meta.destructive,
|
|
85
|
+
rollbackSafe: !!m.meta.rollbackSafe,
|
|
86
|
+
status,
|
|
87
|
+
durationMs: num((applied && applied.durationMs) ?? (dry && dry.durationMs)),
|
|
88
|
+
counts: {
|
|
89
|
+
itemsScanned: num(applyProgress.scanned ?? dryProgress.scanned),
|
|
90
|
+
wouldWrite: num(dryProgress.wouldWrite),
|
|
91
|
+
wouldDelete: num(dryProgress.wouldDelete),
|
|
92
|
+
written: num(applyProgress.written),
|
|
93
|
+
deleted: num(applyProgress.deleted),
|
|
94
|
+
},
|
|
95
|
+
sdkStats: (applied && applied.sdkStats) || (dry && dry.sdkStats) || {},
|
|
96
|
+
restorePoints: (facts && facts.restorePoints) || {},
|
|
97
|
+
backupArns: (facts && facts.backupArns) || [],
|
|
98
|
+
error,
|
|
99
|
+
}
|
|
100
|
+
})
|
|
101
|
+
|
|
102
|
+
let status
|
|
103
|
+
if (p.error) status = RUN_BLOCK_STATUSES.includes(p.error.code) ? p.error.code : 'FAILED'
|
|
104
|
+
else if (migrations.some((m) => m.status === 'failed' || m.status === 'interrupted')) status = 'FAILED'
|
|
105
|
+
else if (migrations.length === 0) status = 'up-to-date'
|
|
106
|
+
else if (migrations.some((m) => m.status === 'awaiting-approval')) status = 'awaiting-approval'
|
|
107
|
+
else if (migrations.every((m) => m.status === 'completed')) status = 'applied'
|
|
108
|
+
else status = 'pending'
|
|
109
|
+
|
|
110
|
+
return {
|
|
111
|
+
serviceRef: p.serviceRef,
|
|
112
|
+
deploymentId: p.deploymentId || null,
|
|
113
|
+
commitSha: p.commitSha || null,
|
|
114
|
+
source: p.source,
|
|
115
|
+
runId: p.runId,
|
|
116
|
+
phase: p.phase,
|
|
117
|
+
mode: p.mode,
|
|
118
|
+
startedAt: p.startedAt,
|
|
119
|
+
finishedAt: p.finishedAt,
|
|
120
|
+
ledger: { tableName: p.ledger.tableName, scope: p.ledger.scope, stage: p.ledger.stage },
|
|
121
|
+
status,
|
|
122
|
+
lock: p.lock ? { owner: p.lock.owner, takeover: !!p.lock.takeover } : null,
|
|
123
|
+
migrations,
|
|
124
|
+
approval: p.approval || null,
|
|
125
|
+
...(p.error ? { error: { code: p.error.code, message: p.error.message } } : {}),
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
module.exports = { buildReport }
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
// Load-time migration rules (§2.4): validates each migration's declared metadata and refuses unsafe
|
|
2
|
+
// pre-deploy migrations before any dry-run. Also loads pending migrations with metadata via `plan`.
|
|
3
|
+
const { MigrationError } = require('./errors')
|
|
4
|
+
|
|
5
|
+
const PHASES = ['pre-deploy', 'post-deploy']
|
|
6
|
+
const BACKUP_MODES = ['pitr', 'on-demand']
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* @typedef {{ description?: string, phase: 'pre-deploy'|'post-deploy', destructive: boolean, backup: 'pitr'|'on-demand', rollbackSafe: boolean, tables: string[] }} MigrationMeta
|
|
10
|
+
* @typedef {{ id: string, checksum: string, path?: string, meta: MigrationMeta }} LoadedMigration
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* @param {string} id
|
|
15
|
+
* @param {string} message
|
|
16
|
+
*/
|
|
17
|
+
function invalid(id, message) {
|
|
18
|
+
return new MigrationError('MIGRATION_INVALID', `${id}: ${message}`, { id })
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* @param {{ id: string, meta?: Record<string, unknown> }} migration
|
|
23
|
+
* @param {{ tables: Record<string, string> }} service logical table → physical name from the current outputs
|
|
24
|
+
* @returns {MigrationMeta}
|
|
25
|
+
*/
|
|
26
|
+
function validateMigration({ id, meta = {} }, { tables }) {
|
|
27
|
+
const phase = meta.phase === undefined ? 'post-deploy' : meta.phase
|
|
28
|
+
const backup = meta.backup === undefined ? 'pitr' : meta.backup
|
|
29
|
+
const destructive = meta.destructive === undefined ? false : meta.destructive
|
|
30
|
+
const rollbackSafe = meta.rollbackSafe === undefined ? false : meta.rollbackSafe
|
|
31
|
+
const declared = meta.tables
|
|
32
|
+
|
|
33
|
+
if (!PHASES.includes(/** @type {string} */ (phase))) throw invalid(id, `phase must be one of ${PHASES.join(', ')}`)
|
|
34
|
+
if (!BACKUP_MODES.includes(/** @type {string} */ (backup))) throw invalid(id, `backup must be one of ${BACKUP_MODES.join(', ')}`)
|
|
35
|
+
if (typeof destructive !== 'boolean') throw invalid(id, 'destructive must be a boolean')
|
|
36
|
+
if (typeof rollbackSafe !== 'boolean') throw invalid(id, 'rollbackSafe must be a boolean')
|
|
37
|
+
if (!Array.isArray(declared) || declared.length === 0 || !declared.every((t) => typeof t === 'string' && t.length > 0)) {
|
|
38
|
+
throw invalid(id, 'tables must be a non-empty array of logical table names')
|
|
39
|
+
}
|
|
40
|
+
if (meta.description !== undefined && typeof meta.description !== 'string') throw invalid(id, 'description must be a string')
|
|
41
|
+
|
|
42
|
+
const missing = declared.filter((t) => !tables[t])
|
|
43
|
+
if (phase === 'pre-deploy') {
|
|
44
|
+
if (destructive) {
|
|
45
|
+
throw new MigrationError('PRE_DEPLOY_DESTRUCTIVE', `${id}: a pre-deploy migration must not be destructive (the previous release is still serving)`, { id })
|
|
46
|
+
}
|
|
47
|
+
if (rollbackSafe !== true) {
|
|
48
|
+
throw new MigrationError('PRE_DEPLOY_NOT_ROLLBACK_SAFE', `${id}: a pre-deploy migration must declare rollbackSafe: true`, { id })
|
|
49
|
+
}
|
|
50
|
+
if (missing.length > 0) {
|
|
51
|
+
throw new MigrationError('PRE_DEPLOY_TABLE_MISSING', `${id}: pre-deploy tables not in the current stack outputs: ${missing.join(', ')}`, { id, missing })
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
if (missing.length > 0) {
|
|
55
|
+
throw new MigrationError('MIGRATION_TABLE_OUTPUT_MISSING', `${id}: no stack output resolved for tables: ${missing.join(', ')}`, { id, missing })
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
return {
|
|
59
|
+
description: /** @type {string|undefined} */ (meta.description),
|
|
60
|
+
phase: /** @type {MigrationMeta['phase']} */ (phase),
|
|
61
|
+
destructive,
|
|
62
|
+
backup: /** @type {MigrationMeta['backup']} */ (backup),
|
|
63
|
+
rollbackSafe,
|
|
64
|
+
tables: declared.slice(),
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* @template {{ id: string, meta: { phase: string } }} M
|
|
70
|
+
* @param {M[]} migrations lexical id order
|
|
71
|
+
* @param {'pre'|'post'|'all'} phase
|
|
72
|
+
* @returns {M[]}
|
|
73
|
+
*/
|
|
74
|
+
function selectPhase(migrations, phase) {
|
|
75
|
+
const pre = migrations.filter((m) => m.meta.phase === 'pre-deploy')
|
|
76
|
+
const post = migrations.filter((m) => m.meta.phase === 'post-deploy')
|
|
77
|
+
if (phase === 'pre') return pre
|
|
78
|
+
if (phase === 'post') return post
|
|
79
|
+
if (phase === 'all') return [...pre, ...post]
|
|
80
|
+
throw new MigrationError('MIGRATION_INVALID', `phase must be pre, post or all; got ${String(phase)}`)
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Lists pending migrations with their metadata through the library's `plan` (reads the ledger, imports
|
|
85
|
+
* each pending module) and validates every one. Fails closed on the first invalid migration.
|
|
86
|
+
* @param {{ config: object, stage: string, clients: object, tables: Record<string, string> }} p
|
|
87
|
+
* @returns {Promise<{ pending: LoadedMigration[], drifted: string[] }>}
|
|
88
|
+
*/
|
|
89
|
+
async function loadMigrations({ config, stage, clients, tables }) {
|
|
90
|
+
const { plan } = await import('ddb-migration-tools')
|
|
91
|
+
const result = await plan({ config, stage, clients, includeMeta: true })
|
|
92
|
+
if (result.drifted.length > 0) {
|
|
93
|
+
throw new MigrationError('MIGRATION_CHECKSUM_DRIFT', `completed migrations changed on disk: ${result.drifted.join(', ')}`, { drifted: result.drifted })
|
|
94
|
+
}
|
|
95
|
+
const pending = result.pending.map((p) => ({
|
|
96
|
+
id: p.id,
|
|
97
|
+
checksum: p.checksum,
|
|
98
|
+
path: p.path,
|
|
99
|
+
meta: validateMigration({ id: p.id, meta: p.meta }, { tables }),
|
|
100
|
+
}))
|
|
101
|
+
return { pending, drifted: result.drifted }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
module.exports = { validateMigration, selectPhase, loadMigrations, PHASES }
|
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
// runServiceMigrations: one service's migrations for one phase against its own ledger — lease, plan,
|
|
2
|
+
// IAM-enforced dry-run child, gate, backup check, apply child, release, report. Shared by deployer and CLI.
|
|
3
|
+
const path = require('path')
|
|
4
|
+
const { DescribeTableCommand, DynamoDBClient } = require('@aws-sdk/client-dynamodb')
|
|
5
|
+
const { DynamoDBDocumentClient } = require('@aws-sdk/lib-dynamodb')
|
|
6
|
+
const { assumeMigrateRole, migrateSessionName, SESSION_PREFIX } = require('./credentials')
|
|
7
|
+
const { runStepChild } = require('./child')
|
|
8
|
+
const { checkBackups } = require('./backups')
|
|
9
|
+
const { splitByGate } = require('./gate')
|
|
10
|
+
const { loadMigrations, selectPhase } = require('./rules')
|
|
11
|
+
const { buildReport } = require('./report')
|
|
12
|
+
const { MigrationError, toErrorInfo } = require('./errors')
|
|
13
|
+
const { debugRun } = require('./log')
|
|
14
|
+
|
|
15
|
+
// Lease outlives the phase timeout by 5 minutes so a slow finish never loses it.
|
|
16
|
+
const LEASE_GRACE_SECONDS = 300
|
|
17
|
+
const MAX_HEARTBEAT_MS = 60 * 1000
|
|
18
|
+
// Library/child codes mapped onto the pipeline's failure taxonomy names.
|
|
19
|
+
const CODE_MAP = { LOCK_HELD: 'MIGRATION_LOCKED', LEDGER_MISSING: 'MIGRATION_LEDGER_MISSING' }
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* @typedef {{
|
|
23
|
+
* service: { ref: string, dir: string, migrationsDir: string, tables: Record<string, string> },
|
|
24
|
+
* ledger: { tableName: string, scope: string, stage: string },
|
|
25
|
+
* role: { roleArn?: string, sourceCredentials?: any, sessionPrefix?: string },
|
|
26
|
+
* region: string,
|
|
27
|
+
* accountId?: string,
|
|
28
|
+
* endpoint?: string,
|
|
29
|
+
* phase: 'pre'|'post'|'all',
|
|
30
|
+
* mode: 'plan'|'dry-run'|'apply',
|
|
31
|
+
* gate: { policy: 'auto'|'destructive'|'all', protected: boolean, approval?: any },
|
|
32
|
+
* run: { runId: string, appliedBy: string, source: 'deployer'|'self', commitSha?: string, lockOwner?: string },
|
|
33
|
+
* params?: Record<string, unknown>,
|
|
34
|
+
* faultInjection?: { failAfterCheckpoints: number },
|
|
35
|
+
* timeoutSeconds: number,
|
|
36
|
+
* estimateSeconds?: (migration: { id: string, meta: any }) => Promise<number>,
|
|
37
|
+
* onReport?: (report: object) => Promise<void>,
|
|
38
|
+
* onOutput?: (chunk: string) => void,
|
|
39
|
+
* onEvent?: (event: { type: string, id: string }) => void,
|
|
40
|
+
* signal?: AbortSignal,
|
|
41
|
+
* }} RunOptions
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* @param {unknown} err
|
|
46
|
+
* @returns {{ code: string, message: string }}
|
|
47
|
+
*/
|
|
48
|
+
function errorOf(err) {
|
|
49
|
+
const info = toErrorInfo(err)
|
|
50
|
+
const code = CODE_MAP[info.code] || info.code
|
|
51
|
+
return { code, message: info.message.replace(/^[A-Z][A-Z0-9_]+: /, '') }
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* @param {{ results?: any[] }} upResult
|
|
56
|
+
* @returns {Record<string, any>}
|
|
57
|
+
*/
|
|
58
|
+
function resultsById(upResult) {
|
|
59
|
+
return Object.fromEntries((upResult.results || []).map((r) => [r.id, r]))
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* @param {{ ledgerRaw: any, tableName: string }} p
|
|
64
|
+
*/
|
|
65
|
+
async function assertLedgerExists({ ledgerRaw, tableName }) {
|
|
66
|
+
try {
|
|
67
|
+
await ledgerRaw.send(new DescribeTableCommand({ TableName: tableName }))
|
|
68
|
+
} catch (err) {
|
|
69
|
+
if (err && err.name === 'ResourceNotFoundException') {
|
|
70
|
+
throw new MigrationError('MIGRATION_LEDGER_MISSING', `ledger table ${tableName} does not exist`)
|
|
71
|
+
}
|
|
72
|
+
throw err
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* The library config object for one service's ledger stage (nothing is read from cwd).
|
|
78
|
+
* @param {Pick<RunOptions, 'service'|'ledger'|'region'|'accountId'|'endpoint'>} opts
|
|
79
|
+
*/
|
|
80
|
+
function libraryConfig({ service, ledger, region, accountId, endpoint }) {
|
|
81
|
+
return {
|
|
82
|
+
appName: service.ref,
|
|
83
|
+
migrationsDir: path.resolve(service.dir, service.migrationsDir),
|
|
84
|
+
ledger: { tableName: ledger.tableName, scope: ledger.scope, create: false },
|
|
85
|
+
stages: { [ledger.stage]: { region, accountId, tables: service.tables, ...(endpoint ? { endpoint } : {}) } },
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* @param {RunOptions} opts
|
|
91
|
+
* @param {{ assumeMigrateRole?: typeof assumeMigrateRole, runStepChild?: typeof runStepChild, checkBackups?: typeof checkBackups, now?: () => number }} [deps]
|
|
92
|
+
* @returns {Promise<object>} the §2.17.6 report (plus reportError when onReport failed)
|
|
93
|
+
*/
|
|
94
|
+
async function runServiceMigrations(opts, deps = {}) {
|
|
95
|
+
const assume = deps.assumeMigrateRole || assumeMigrateRole
|
|
96
|
+
const stepChild = deps.runStepChild || runStepChild
|
|
97
|
+
const backupCheck = deps.checkBackups || checkBackups
|
|
98
|
+
const now = deps.now || Date.now
|
|
99
|
+
const startedAt = new Date(now()).toISOString()
|
|
100
|
+
const { service, ledger, run, gate } = opts
|
|
101
|
+
const lockOwner = run.lockOwner || run.appliedBy
|
|
102
|
+
|
|
103
|
+
/** @type {{ id: string, checksum: string, path?: string, meta: any }[]} */
|
|
104
|
+
let considered = []
|
|
105
|
+
const dryRun = {}
|
|
106
|
+
const apply = {}
|
|
107
|
+
const backups = {}
|
|
108
|
+
const waiting = []
|
|
109
|
+
/** @type {{ code: string, message: string }|null} */
|
|
110
|
+
let error = null
|
|
111
|
+
let lockInfo = null
|
|
112
|
+
let ledgerRows = {}
|
|
113
|
+
|
|
114
|
+
const finish = async () => {
|
|
115
|
+
const report = buildReport({
|
|
116
|
+
serviceRef: service.ref,
|
|
117
|
+
deploymentId: opts.params && typeof opts.params.deploymentId === 'string' ? opts.params.deploymentId : null,
|
|
118
|
+
commitSha: run.commitSha,
|
|
119
|
+
source: run.source,
|
|
120
|
+
runId: run.runId,
|
|
121
|
+
phase: opts.phase,
|
|
122
|
+
mode: opts.mode,
|
|
123
|
+
startedAt,
|
|
124
|
+
finishedAt: new Date(now()).toISOString(),
|
|
125
|
+
ledger,
|
|
126
|
+
lock: lockInfo,
|
|
127
|
+
migrations: considered,
|
|
128
|
+
ledgerRows,
|
|
129
|
+
dryRun,
|
|
130
|
+
apply,
|
|
131
|
+
backups,
|
|
132
|
+
waiting,
|
|
133
|
+
approval: gate.approval || null,
|
|
134
|
+
error,
|
|
135
|
+
})
|
|
136
|
+
debugRun('report service=%s phase=%s mode=%s status=%s', service.ref, opts.phase, opts.mode, report.status)
|
|
137
|
+
if (!opts.onReport) return report
|
|
138
|
+
try {
|
|
139
|
+
await opts.onReport(report)
|
|
140
|
+
return report
|
|
141
|
+
} catch (err) {
|
|
142
|
+
// The ledger already holds the outcome; a lost report is re-sent later, never re-applied.
|
|
143
|
+
debugRun('report delivery failed service=%s reason=%s', service.ref, toErrorInfo(err).code)
|
|
144
|
+
return { ...report, reportError: toErrorInfo(err) }
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// Proof knob (non-protected deployments only): the apply child fails after its Nth checkpoint write.
|
|
149
|
+
const fault = opts.faultInjection
|
|
150
|
+
if (fault && !(Number.isInteger(fault.failAfterCheckpoints) && fault.failAfterCheckpoints > 0)) {
|
|
151
|
+
error = { code: 'INVALID_FAULT_INJECTION', message: `faultInjection.failAfterCheckpoints must be a positive integer; got ${String(fault.failAfterCheckpoints)}` }
|
|
152
|
+
return finish()
|
|
153
|
+
}
|
|
154
|
+
if (!ledger || !ledger.tableName) {
|
|
155
|
+
error = { code: 'MIGRATION_LEDGER_MISSING', message: 'no MigrationsLedgerTableName output for this service' }
|
|
156
|
+
return finish()
|
|
157
|
+
}
|
|
158
|
+
if (!opts.role || !opts.role.roleArn) {
|
|
159
|
+
error = { code: 'MIGRATE_ROLE_MISSING', message: 'no MigrateRoleArn output for this service (no trusted principal?)' }
|
|
160
|
+
return finish()
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
const stage = ledger.stage
|
|
164
|
+
const config = libraryConfig(opts)
|
|
165
|
+
const sessionPrefix = opts.role.sessionPrefix || SESSION_PREFIX
|
|
166
|
+
const fullSession = assume({
|
|
167
|
+
roleArn: opts.role.roleArn,
|
|
168
|
+
sourceCredentials: opts.role.sourceCredentials,
|
|
169
|
+
readOnly: false,
|
|
170
|
+
region: opts.region,
|
|
171
|
+
sessionName: migrateSessionName({ prefix: sessionPrefix, kind: 'apply', runId: run.runId }),
|
|
172
|
+
})
|
|
173
|
+
const clientConfig = { region: opts.region, credentials: fullSession, ...(opts.endpoint ? { endpoint: opts.endpoint } : {}) }
|
|
174
|
+
const ledgerRaw = new DynamoDBClient(clientConfig)
|
|
175
|
+
const ledgerDoc = DynamoDBDocumentClient.from(ledgerRaw)
|
|
176
|
+
const lib = await import('ddb-migration-tools')
|
|
177
|
+
const lockParams = { ledgerClient: ledgerDoc, tableName: ledger.tableName, scope: ledger.scope, stage, owner: lockOwner }
|
|
178
|
+
const ttlSeconds = opts.timeoutSeconds + LEASE_GRACE_SECONDS
|
|
179
|
+
|
|
180
|
+
/** @type {NodeJS.Timeout|undefined} */
|
|
181
|
+
let heartbeat
|
|
182
|
+
const stepAbort = new AbortController()
|
|
183
|
+
const forwardAbort = () => stepAbort.abort()
|
|
184
|
+
if (opts.signal) opts.signal.addEventListener('abort', forwardAbort, { once: true })
|
|
185
|
+
let acquired = false
|
|
186
|
+
|
|
187
|
+
try {
|
|
188
|
+
await assertLedgerExists({ ledgerRaw, tableName: ledger.tableName })
|
|
189
|
+
const loaded = await loadMigrations({ config, stage, clients: { ledger: { raw: ledgerRaw } }, tables: service.tables })
|
|
190
|
+
considered = selectPhase(loaded.pending, opts.phase)
|
|
191
|
+
if (opts.mode === 'plan' || considered.length === 0) return await finish()
|
|
192
|
+
|
|
193
|
+
try {
|
|
194
|
+
const lease = await lib.acquireLock({ ...lockParams, ttlSeconds })
|
|
195
|
+
acquired = true
|
|
196
|
+
lockInfo = { owner: lockOwner, takeover: lease.takeover }
|
|
197
|
+
} catch (err) {
|
|
198
|
+
if (err && err.code === 'LOCK_HELD') {
|
|
199
|
+
throw new MigrationError('MIGRATION_LOCKED', `ledger lease held by ${err.holder} until ${new Date(err.expiresAt * 1000).toISOString()}`)
|
|
200
|
+
}
|
|
201
|
+
throw err
|
|
202
|
+
}
|
|
203
|
+
heartbeat = setInterval(() => {
|
|
204
|
+
lib.heartbeatLock({ ...lockParams, ttlSeconds }).catch((err) => {
|
|
205
|
+
debugRun('lease heartbeat failed reason=%s; stopping step', toErrorInfo(err).code)
|
|
206
|
+
stepAbort.abort()
|
|
207
|
+
})
|
|
208
|
+
}, Math.min(MAX_HEARTBEAT_MS, (ttlSeconds * 1000) / 3))
|
|
209
|
+
heartbeat.unref()
|
|
210
|
+
|
|
211
|
+
const readOnlySession = assume({
|
|
212
|
+
roleArn: opts.role.roleArn,
|
|
213
|
+
sourceCredentials: opts.role.sourceCredentials,
|
|
214
|
+
readOnly: true,
|
|
215
|
+
region: opts.region,
|
|
216
|
+
sessionName: migrateSessionName({ prefix: sessionPrefix, kind: 'dryrun', runId: run.runId }),
|
|
217
|
+
})
|
|
218
|
+
const tablesById = Object.fromEntries(considered.map((m) => [m.id, m.meta.tables.map((t) => service.tables[t])]))
|
|
219
|
+
const request = (dryRunStep, only) => ({
|
|
220
|
+
stage,
|
|
221
|
+
config,
|
|
222
|
+
cwd: service.dir,
|
|
223
|
+
dryRun: dryRunStep,
|
|
224
|
+
only,
|
|
225
|
+
appliedBy: run.appliedBy,
|
|
226
|
+
params: opts.params || {},
|
|
227
|
+
lockOwner,
|
|
228
|
+
tablesById,
|
|
229
|
+
...(fault && !dryRunStep ? { faultInjection: fault } : {}),
|
|
230
|
+
})
|
|
231
|
+
const step = (credentials, dryRunStep, only) => stepChild({
|
|
232
|
+
credentials,
|
|
233
|
+
region: opts.region,
|
|
234
|
+
request: request(dryRunStep, only),
|
|
235
|
+
cwd: service.dir,
|
|
236
|
+
onOutput: opts.onOutput,
|
|
237
|
+
onEvent: opts.onEvent,
|
|
238
|
+
signal: stepAbort.signal,
|
|
239
|
+
})
|
|
240
|
+
|
|
241
|
+
const passes = opts.phase === 'all' ? ['pre', 'post'] : [opts.phase]
|
|
242
|
+
for (const pass of passes) {
|
|
243
|
+
const migrations = selectPhase(considered, pass)
|
|
244
|
+
if (migrations.length === 0) continue
|
|
245
|
+
|
|
246
|
+
const dry = await step(readOnlySession, true, migrations.map((m) => m.id))
|
|
247
|
+
Object.assign(dryRun, resultsById(dry))
|
|
248
|
+
if (dry.failed || dry.interrupted) break
|
|
249
|
+
|
|
250
|
+
if (opts.estimateSeconds) {
|
|
251
|
+
for (const m of migrations) {
|
|
252
|
+
const estimate = await opts.estimateSeconds(m)
|
|
253
|
+
if (estimate > opts.timeoutSeconds) {
|
|
254
|
+
throw new MigrationError('MIGRATION_TOO_LARGE', `${m.id} estimated ${estimate}s exceeds the ${opts.timeoutSeconds}s window`)
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
if (opts.mode === 'dry-run') continue
|
|
259
|
+
|
|
260
|
+
const split = splitByGate({ ...gate, serviceRef: service.ref, migrations })
|
|
261
|
+
waiting.push(...split.waiting.map((m) => m.id))
|
|
262
|
+
const toApply = []
|
|
263
|
+
for (const m of split.apply) {
|
|
264
|
+
if (m.meta.destructive) {
|
|
265
|
+
const result = await backupCheck({
|
|
266
|
+
dynamo: new DynamoDBClient(clientConfig),
|
|
267
|
+
tables: m.meta.tables.map((t) => service.tables[t]),
|
|
268
|
+
mode: m.meta.backup,
|
|
269
|
+
protected: gate.protected,
|
|
270
|
+
label: m.id,
|
|
271
|
+
})
|
|
272
|
+
backups[m.id] = result
|
|
273
|
+
if (result.status !== 'ok') {
|
|
274
|
+
const why = result.blockedTables ? `PITR not enabled on ${result.blockedTables.join(', ')}` : (result.error && result.error.message)
|
|
275
|
+
error = { code: 'BLOCKED_NO_BACKUP', message: `${m.id}: ${why}` }
|
|
276
|
+
break
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
toApply.push(m)
|
|
280
|
+
}
|
|
281
|
+
if (toApply.length > 0) {
|
|
282
|
+
const applied = await step(fullSession, false, toApply.map((m) => m.id))
|
|
283
|
+
Object.assign(apply, resultsById(applied))
|
|
284
|
+
if (applied.failed || applied.interrupted) break
|
|
285
|
+
}
|
|
286
|
+
if (error || waiting.length > 0) break
|
|
287
|
+
}
|
|
288
|
+
} catch (err) {
|
|
289
|
+
error = errorOf(err)
|
|
290
|
+
debugRun('run stopped service=%s reason=%s', service.ref, error.code)
|
|
291
|
+
} finally {
|
|
292
|
+
if (heartbeat) clearInterval(heartbeat)
|
|
293
|
+
if (opts.signal) opts.signal.removeEventListener('abort', forwardAbort)
|
|
294
|
+
if (acquired) {
|
|
295
|
+
await lib.releaseLock(lockParams).catch((err) => debugRun('lease release failed reason=%s', toErrorInfo(err).code))
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
if (considered.length > 0) {
|
|
300
|
+
try {
|
|
301
|
+
const statuses = await lib.status({ config, stage, clients: { ledger: { raw: ledgerRaw } } })
|
|
302
|
+
ledgerRows = Object.fromEntries(statuses.filter((s) => s.status !== 'pending' && s.status !== 'orphan').map((s) => [s.id, { status: s.status, appliedAt: s.appliedAt }]))
|
|
303
|
+
} catch (err) {
|
|
304
|
+
debugRun('ledger re-read failed reason=%s', toErrorInfo(err).code)
|
|
305
|
+
if (!error) error = errorOf(err)
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
return finish()
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
module.exports = { runServiceMigrations, libraryConfig, assertLedgerExists, errorOf }
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// Read-only STS session policy for migration dry-runs. Passed as `Policy` when assuming the migrate
|
|
2
|
+
// role, so the session's effective permissions (role ∩ session) reject every DynamoDB write.
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* @template T
|
|
6
|
+
* @param {T} value
|
|
7
|
+
* @returns {Readonly<T>}
|
|
8
|
+
*/
|
|
9
|
+
function deepFreeze(value) {
|
|
10
|
+
if (value && typeof value === 'object') {
|
|
11
|
+
for (const inner of Object.values(value)) deepFreeze(inner)
|
|
12
|
+
Object.freeze(value)
|
|
13
|
+
}
|
|
14
|
+
return value
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
// Resource '*' is safe: a session policy only removes permissions, and the role policy already limits
|
|
18
|
+
// resources to the service's own tables and ledger.
|
|
19
|
+
const readOnlySessionPolicy = deepFreeze({
|
|
20
|
+
Version: '2012-10-17',
|
|
21
|
+
Statement: [{
|
|
22
|
+
Sid: 'MigrationDryRunReadOnly',
|
|
23
|
+
Effect: 'Allow',
|
|
24
|
+
Action: [
|
|
25
|
+
'dynamodb:GetItem',
|
|
26
|
+
'dynamodb:BatchGetItem',
|
|
27
|
+
'dynamodb:Query',
|
|
28
|
+
'dynamodb:Scan',
|
|
29
|
+
'dynamodb:DescribeTable',
|
|
30
|
+
'dynamodb:DescribeContinuousBackups',
|
|
31
|
+
'dynamodb:DescribeBackup',
|
|
32
|
+
],
|
|
33
|
+
Resource: '*',
|
|
34
|
+
}],
|
|
35
|
+
})
|
|
36
|
+
|
|
37
|
+
module.exports = { readOnlySessionPolicy, deepFreeze }
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
// Client-side guard on the migration app client: refuses any table the active migration did not declare
|
|
2
|
+
// (UNDECLARED_TABLE) and, in a dry-run, any non-read command (DRY_RUN_WRITE_BLOCKED). IAM stays the guarantee.
|
|
3
|
+
const { MigrationError } = require('./errors')
|
|
4
|
+
|
|
5
|
+
// Command-name prefixes a dry-run may send. Everything else (writes, backups, table changes) is refused.
|
|
6
|
+
const DRY_RUN_ALLOWED = ['Get', 'BatchGet', 'TransactGet', 'Query', 'Scan', 'Describe', 'List']
|
|
7
|
+
// PartiQL statements carry table names inside SQL text, which this guard cannot check.
|
|
8
|
+
const UNGUARDABLE = ['ExecuteStatementCommand', 'BatchExecuteStatementCommand', 'ExecuteTransactionCommand']
|
|
9
|
+
const WRITE_ACTIONS = ['PutItem', 'UpdateItem', 'DeleteItem', 'BatchWriteItem', 'TransactWriteItems', 'CreateBackup']
|
|
10
|
+
|
|
11
|
+
/** @param {string} tableNameOrArn */
|
|
12
|
+
function tableOf(tableNameOrArn) {
|
|
13
|
+
const i = tableNameOrArn.indexOf(':table/')
|
|
14
|
+
if (i === -1) return tableNameOrArn
|
|
15
|
+
return tableNameOrArn.slice(i + ':table/'.length).split('/')[0]
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @param {Record<string, any>} input
|
|
20
|
+
* @returns {string[]}
|
|
21
|
+
*/
|
|
22
|
+
function tablesInInput(input) {
|
|
23
|
+
const out = []
|
|
24
|
+
if (typeof input.TableName === 'string') out.push(input.TableName)
|
|
25
|
+
if (input.RequestItems && typeof input.RequestItems === 'object') out.push(...Object.keys(input.RequestItems))
|
|
26
|
+
if (Array.isArray(input.TransactItems)) {
|
|
27
|
+
for (const item of input.TransactItems) {
|
|
28
|
+
for (const op of Object.values(item || {})) {
|
|
29
|
+
if (op && typeof op.TableName === 'string') out.push(op.TableName)
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
return out.map(tableOf)
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Adds the guard to the raw client's middleware stack, which the library's document client shares.
|
|
38
|
+
* @param {{ middlewareStack: { add: Function } }} raw
|
|
39
|
+
* @param {{ dryRun: boolean, tablesFor: (migrationId: string) => string[] }} opts physical table names per migration
|
|
40
|
+
* @returns {{ setActiveMigration: (id: string|undefined) => void }}
|
|
41
|
+
*/
|
|
42
|
+
function guardAppClient(raw, { dryRun, tablesFor }) {
|
|
43
|
+
/** @type {string|undefined} */
|
|
44
|
+
let active
|
|
45
|
+
|
|
46
|
+
const middleware = (next, context) => async (args) => {
|
|
47
|
+
const command = context.commandName || 'UnknownCommand'
|
|
48
|
+
const tables = tablesInInput(args.input || {})
|
|
49
|
+
if (UNGUARDABLE.includes(command)) {
|
|
50
|
+
throw new MigrationError('UNDECLARED_TABLE', `${command} cannot be table-guarded; use item commands`, { command })
|
|
51
|
+
}
|
|
52
|
+
if (tables.length > 0) {
|
|
53
|
+
const allowed = active ? tablesFor(active) : []
|
|
54
|
+
const undeclared = tables.filter((t) => !allowed.includes(t))
|
|
55
|
+
if (undeclared.length > 0) {
|
|
56
|
+
throw new MigrationError('UNDECLARED_TABLE', `${active || '(no active migration)'} sent ${command} to undeclared tables: ${undeclared.join(', ')}`, { migrationId: active, command })
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
if (dryRun && !DRY_RUN_ALLOWED.some((prefix) => command.startsWith(prefix))) {
|
|
60
|
+
throw new MigrationError('DRY_RUN_WRITE_BLOCKED', `${command} on ${tables.join(', ') || '(no table)'} refused during dry-run`, { migrationId: active, command })
|
|
61
|
+
}
|
|
62
|
+
return next(args)
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
raw.middlewareStack.add(middleware, { step: 'initialize', name: 'saaslayerMigrationStepGuard', priority: 'high' })
|
|
66
|
+
return { setActiveMigration: (id) => { active = id } }
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Maps a dry-run failure message to its code. An IAM denial of a write action (a migration that built
|
|
71
|
+
* its own client) and the client guard's refusal both mean the migration tried to write.
|
|
72
|
+
* @param {string} message
|
|
73
|
+
* @returns {'DRY_RUN_WRITE_BLOCKED'|'MIGRATION_FAILED'}
|
|
74
|
+
*/
|
|
75
|
+
function classifyDryRunFailure(message) {
|
|
76
|
+
if (/^DRY_RUN_WRITE_BLOCKED\b/.test(message)) return 'DRY_RUN_WRITE_BLOCKED'
|
|
77
|
+
const denied = /not authorized to perform: dynamodb:(\w+)/.exec(message)
|
|
78
|
+
if (denied && WRITE_ACTIONS.includes(denied[1])) return 'DRY_RUN_WRITE_BLOCKED'
|
|
79
|
+
return 'MIGRATION_FAILED'
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
module.exports = { guardAppClient, classifyDryRunFailure, tablesInInput }
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// Types for the deployment activity feed (activity.js): entries projected from deployer runs and recorded
|
|
2
|
+
// non-run actions, each attributed to a customer or operator actor.
|
|
3
|
+
export type ActorKind = 'customer' | 'operator'
|
|
4
|
+
export interface Actor { kind: ActorKind; id: string }
|
|
5
|
+
export interface ActivityEntry {
|
|
6
|
+
id: string
|
|
7
|
+
at: string | null
|
|
8
|
+
actor: Actor | null
|
|
9
|
+
action: string
|
|
10
|
+
subject: string | null
|
|
11
|
+
reason: string | null
|
|
12
|
+
operationId: string | null
|
|
13
|
+
status?: string
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export const ACTOR_KINDS: ActorKind[]
|
|
17
|
+
export function actorOf(value: unknown): Actor | null
|
|
18
|
+
export function activityFromRun(run: Record<string, unknown>): ActivityEntry
|
|
19
|
+
export function activityFromRecord(record: Record<string, unknown>): ActivityEntry
|
|
20
|
+
export function activityFeed(input: { runs?: Array<Record<string, unknown>>; records?: Array<Record<string, unknown>>; limit?: number }): ActivityEntry[]
|
|
21
|
+
export function formatActivity(entries: ActivityEntry[]): string[]
|