blogwright 0.4.0 → 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/README.md +4 -1
- package/agent/agent-manifest.json +1 -1
- package/agent/server.js +2610 -616
- package/dist/adapters/process-aws-login.d.ts +19 -0
- package/dist/adapters/process-aws-login.js +28 -0
- package/dist/agent-package.js +2 -3
- package/dist/artifacts.d.ts +73 -0
- package/dist/artifacts.js +218 -0
- package/dist/aws-session.d.ts +118 -0
- package/dist/aws-session.js +360 -0
- package/dist/bin.js +6 -2
- package/dist/cache-control.d.ts +66 -0
- package/dist/cache-control.js +176 -0
- package/dist/cli.d.ts +22 -3
- package/dist/cli.js +122 -31
- package/dist/commands.d.ts +41 -9
- package/dist/commands.js +135 -126
- package/dist/context.d.ts +27 -5
- package/dist/context.js +59 -19
- package/dist/deploy.d.ts +78 -6
- package/dist/deploy.js +136 -52
- package/dist/init.d.ts +14 -2
- package/dist/init.js +145 -4
- package/dist/known-commands.d.ts +11 -9
- package/dist/known-commands.js +15 -9
- package/dist/live-release.d.ts +78 -0
- package/dist/live-release.js +159 -0
- package/dist/lock.d.ts +50 -0
- package/dist/lock.js +120 -0
- package/dist/nodes.d.ts +18 -0
- package/dist/nodes.js +405 -30
- package/dist/plugin-commands.d.ts +21 -0
- package/dist/plugin-commands.js +54 -3
- package/dist/plugins.d.ts +11 -9
- package/dist/plugins.js +29 -16
- package/dist/ports.d.ts +22 -1
- package/dist/releases.d.ts +54 -0
- package/dist/releases.js +527 -0
- package/dist/render.d.ts +18 -1
- package/dist/render.js +38 -6
- package/dist/repo.js +2 -3
- package/dist/rkey.d.ts +4 -3
- package/dist/rkey.js +4 -3
- package/dist/serving.d.ts +28 -0
- package/dist/serving.js +47 -0
- package/dist/verify.d.ts +45 -0
- package/dist/verify.js +183 -0
- package/dist/whoami.d.ts +23 -0
- package/dist/whoami.js +88 -0
- package/package.json +8 -8
package/dist/init.js
CHANGED
|
@@ -11,8 +11,10 @@
|
|
|
11
11
|
* plugins as a plain array, never a `ModuleLoader`, so this stays a domain
|
|
12
12
|
* module.
|
|
13
13
|
*/
|
|
14
|
-
import { colors, findRepoRoot, parseConfig, WEB_FUNCTION_REGIONS, } from 'blogwright-core';
|
|
14
|
+
import { colors, findRepoRoot, parseConfig, readAwsProfiles, shortIdentity, WEB_FUNCTION_REGIONS, } from 'blogwright-core';
|
|
15
|
+
import { resolveAwsProfile, resolveAwsSession } from './aws-session.js';
|
|
15
16
|
import { renderConfigBlock } from './config-block.js';
|
|
17
|
+
import { confirm } from './logger.js';
|
|
16
18
|
const SITE_NAME_PATTERN = /^[a-z0-9-]+$/;
|
|
17
19
|
const GITHUB_REPO_PATTERN = /^[\w.-]+\/[\w.-]+$/;
|
|
18
20
|
const MAX_ATTEMPTS = 3;
|
|
@@ -223,6 +225,135 @@ async function askSsrFramework(terminal, logger) {
|
|
|
223
225
|
});
|
|
224
226
|
return SSR_FRAMEWORKS[choice.toLowerCase()];
|
|
225
227
|
}
|
|
228
|
+
/** Where the wizard writes, relative to the repo root - also how AWS messages name it. */
|
|
229
|
+
const INIT_CONFIG_FILE = 'config/production.jsonc';
|
|
230
|
+
/** The answer that chooses default credentials when the profile question has a default. */
|
|
231
|
+
const NO_PROFILE_ANSWER = 'none';
|
|
232
|
+
/** The profile `--profile`, then `AWS_PROFILE`, suggests - with which of the two it came from. */
|
|
233
|
+
function suggestedProfile(aws) {
|
|
234
|
+
const flag = aws.profile?.trim();
|
|
235
|
+
if (flag)
|
|
236
|
+
return { name: flag, source: '--profile' };
|
|
237
|
+
const env = aws.host.processEnv.AWS_PROFILE?.trim();
|
|
238
|
+
return env ? { name: env, source: 'AWS_PROFILE' } : undefined;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* Ask which named profile this environment uses - only when the shared AWS
|
|
242
|
+
* files define at least one. Defaults to `--profile`, then `AWS_PROFILE`,
|
|
243
|
+
* but only when the files define it: a stale suggestion is dropped with a
|
|
244
|
+
* warning (even when nothing is asked) rather than offered as an answer that can never validate. Blank
|
|
245
|
+
* means default credentials when there is no default; with a default, blank
|
|
246
|
+
* takes it and `none` chooses default credentials. A nonblank answer must be
|
|
247
|
+
* a listed profile. Undefined means default credentials.
|
|
248
|
+
*/
|
|
249
|
+
async function askAwsProfile(fs, terminal, logger, aws) {
|
|
250
|
+
const profiles = await readAwsProfiles(fs, aws.host.processEnv, aws.host.home);
|
|
251
|
+
const suggested = suggestedProfile(aws);
|
|
252
|
+
const asked = profiles.names.length > 0;
|
|
253
|
+
if (suggested && !profiles.has(suggested.name)) {
|
|
254
|
+
logger.warn(`profile "${suggested.name}" from ${suggested.source} is not in your AWS config files - ` +
|
|
255
|
+
(asked ? 'not offering it as the default' : 'ignoring it'));
|
|
256
|
+
}
|
|
257
|
+
if (!asked)
|
|
258
|
+
return undefined;
|
|
259
|
+
const defaultValue = suggested && profiles.has(suggested.name) ? suggested.name : undefined;
|
|
260
|
+
const choice = defaultValue
|
|
261
|
+
? `"${NO_PROFILE_ANSWER}" for default credentials`
|
|
262
|
+
: 'blank for default credentials';
|
|
263
|
+
const answer = await ask(terminal, logger, {
|
|
264
|
+
prompt: `AWS profile for this environment (${choice})`,
|
|
265
|
+
defaultValue,
|
|
266
|
+
validate: (v) => profiles.has(v) || v === NO_PROFILE_ANSWER
|
|
267
|
+
? undefined
|
|
268
|
+
: `no profile "${v}" - expected one of ${profiles.names.join(', ')}, or "${NO_PROFILE_ANSWER}"`,
|
|
269
|
+
});
|
|
270
|
+
return answer === NO_PROFILE_ANSWER && !profiles.has(answer) ? undefined : answer;
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* Warn when this shell would override what the config is about to say: the
|
|
274
|
+
* pin is detected for the config's credentials, so a command run here under
|
|
275
|
+
* a different `AWS_PROFILE` or exported credentials could be refused.
|
|
276
|
+
*/
|
|
277
|
+
function warnShellOverride(logger, processEnv, profile) {
|
|
278
|
+
const shell = resolveAwsProfile({ processEnv, config: { profile } });
|
|
279
|
+
const advice = 'unset it before running blogwright in this shell';
|
|
280
|
+
if (shell.source === 'env' && shell.name !== profile) {
|
|
281
|
+
const saved = profile === undefined ? 'is not saved to the config' : 'overrides aws.profile';
|
|
282
|
+
logger.warn(`AWS_PROFILE=${shell.name} is set in this shell and ${saved} - ${advice}`);
|
|
283
|
+
}
|
|
284
|
+
else if (shell.source === 'env-keys' && profile !== undefined) {
|
|
285
|
+
logger.warn('AWS credentials exported in this shell override aws.profile - unset them first');
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
/** The environment without `AWS_PROFILE`, so detection sees what a config with no profile uses. */
|
|
289
|
+
function withoutAwsProfile(processEnv) {
|
|
290
|
+
const { AWS_PROFILE: _ignored, ...rest } = processEnv;
|
|
291
|
+
return rest;
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* Offer to detect the account the chosen credentials belong to and pin it.
|
|
295
|
+
* The credentials are the ones the written config selects: the chosen
|
|
296
|
+
* profile, or - with none - exported credentials or the default chain, never
|
|
297
|
+
* this shell's `AWS_PROFILE`, which the config does not record. A shell that
|
|
298
|
+
* would override the config is warned about. Runs the same session
|
|
299
|
+
* resolution every command does - login offer included - against real AWS,
|
|
300
|
+
* so the pin is a real account. With `AWS_ENDPOINT_URL`
|
|
301
|
+
* exported it is not offered at all: the SDK's own SSO and STS clients that
|
|
302
|
+
* resolve a profile read that variable too, so detection would ask the
|
|
303
|
+
* emulator. An AWS failure never fails `init`: every error the session
|
|
304
|
+
* raises is an AWS or sign-in failure, so it warns and leaves the account
|
|
305
|
+
* unpinned.
|
|
306
|
+
*/
|
|
307
|
+
async function askAccountPin(fs, terminal, logger, opts) {
|
|
308
|
+
if (opts.aws.host.processEnv.AWS_ENDPOINT_URL?.trim()) {
|
|
309
|
+
logger.warn('AWS_ENDPOINT_URL is set, so the AWS account cannot be detected');
|
|
310
|
+
logger.warn(ACCOUNT_NOT_PINNED);
|
|
311
|
+
return undefined;
|
|
312
|
+
}
|
|
313
|
+
if (!(await confirm(terminal, 'Detect the AWS account and pin it to this config?'))) {
|
|
314
|
+
return undefined;
|
|
315
|
+
}
|
|
316
|
+
const { host } = opts.aws;
|
|
317
|
+
warnShellOverride(logger, host.processEnv, opts.profile);
|
|
318
|
+
try {
|
|
319
|
+
const session = await resolveAwsSession({
|
|
320
|
+
region: opts.region,
|
|
321
|
+
endpointOverride: undefined,
|
|
322
|
+
flag: opts.profile,
|
|
323
|
+
configLabel: INIT_CONFIG_FILE,
|
|
324
|
+
host: opts.profile === undefined
|
|
325
|
+
? { ...host, processEnv: withoutAwsProfile(host.processEnv) }
|
|
326
|
+
: host,
|
|
327
|
+
ports: { fs, terminal, awsLogin: opts.aws.awsLogin },
|
|
328
|
+
logger,
|
|
329
|
+
});
|
|
330
|
+
const { account, arn } = session.identity;
|
|
331
|
+
logger.ok(`AWS account ${account} (${shortIdentity(arn)}) - pinned as aws.accountId`);
|
|
332
|
+
return account;
|
|
333
|
+
}
|
|
334
|
+
catch (err) {
|
|
335
|
+
logger.warn(err instanceof Error ? err.message : String(err));
|
|
336
|
+
logger.warn(ACCOUNT_NOT_PINNED);
|
|
337
|
+
return undefined;
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
const ACCOUNT_NOT_PINNED = 'account not pinned - add aws.accountId later';
|
|
341
|
+
/**
|
|
342
|
+
* The `aws` block, or undefined when there is nothing to write. Rendered in
|
|
343
|
+
* `renderConfigBlock`'s style; the pin carries its own explanatory comment.
|
|
344
|
+
*/
|
|
345
|
+
function renderAwsBlock(aws) {
|
|
346
|
+
const entries = [];
|
|
347
|
+
if (aws.profile)
|
|
348
|
+
entries.push({ prop: `"profile": ${JSON.stringify(aws.profile)}` });
|
|
349
|
+
if (aws.accountId) {
|
|
350
|
+
entries.push({
|
|
351
|
+
prop: `"accountId": "${aws.accountId}"`,
|
|
352
|
+
comment: 'deploys refuse credentials for any other account',
|
|
353
|
+
});
|
|
354
|
+
}
|
|
355
|
+
return entries.length > 0 ? renderConfigBlock('aws', entries) : undefined;
|
|
356
|
+
}
|
|
226
357
|
/** Render one top-level item with its own trailing comma, or none when it is last. */
|
|
227
358
|
function renderTopLevelItem(item, last) {
|
|
228
359
|
const comma = last ? '' : ',';
|
|
@@ -258,6 +389,9 @@ function renderConfig(opts) {
|
|
|
258
389
|
}
|
|
259
390
|
if (opts.ssr)
|
|
260
391
|
items.push({ block: renderConfigBlock('ssr', opts.ssr.entries) });
|
|
392
|
+
const awsBlock = opts.aws ? renderAwsBlock(opts.aws) : undefined;
|
|
393
|
+
if (awsBlock)
|
|
394
|
+
items.push({ block: awsBlock });
|
|
261
395
|
for (const block of opts.pluginBlocks)
|
|
262
396
|
items.push({ block });
|
|
263
397
|
const body = items.map((item, i) => renderTopLevelItem(item, i === items.length - 1));
|
|
@@ -273,14 +407,14 @@ function renderConfig(opts) {
|
|
|
273
407
|
* single `fs.writeText` below ever runs, so the config file stays exactly
|
|
274
408
|
* what it was - absent, on this path - rather than a partial write.
|
|
275
409
|
*/
|
|
276
|
-
export async function initSite(fs, terminal, logger, plugins,
|
|
410
|
+
export async function initSite(fs, terminal, logger, plugins, options) {
|
|
277
411
|
if (!terminal.isInteractive) {
|
|
278
412
|
logger.error('init is an interactive wizard; in CI or plain mode create config/production.jsonc ' +
|
|
279
413
|
'by hand instead (see README - only "region" and "siteName" are required)');
|
|
280
414
|
return 1;
|
|
281
415
|
}
|
|
282
|
-
const repoRoot = root ?? (await findRepoRoot(fs).catch(() => process.cwd()));
|
|
283
|
-
const configPath = `${repoRoot}
|
|
416
|
+
const repoRoot = options.root ?? (await findRepoRoot(fs).catch(() => process.cwd()));
|
|
417
|
+
const configPath = `${repoRoot}/${INIT_CONFIG_FILE}`;
|
|
284
418
|
if (await fs.exists(configPath)) {
|
|
285
419
|
logger.error(`${configPath} already exists - edit it directly, or pass --config elsewhere`);
|
|
286
420
|
return 1;
|
|
@@ -314,6 +448,12 @@ export async function initSite(fs, terminal, logger, plugins, root) {
|
|
|
314
448
|
validate: (v) => (WEB_FUNCTION_REGIONS.includes(v) ? undefined : `expected ${regions}`),
|
|
315
449
|
});
|
|
316
450
|
}
|
|
451
|
+
const profile = await askAwsProfile(fs, terminal, logger, options.aws);
|
|
452
|
+
const accountId = await askAccountPin(fs, terminal, logger, {
|
|
453
|
+
region: region,
|
|
454
|
+
profile,
|
|
455
|
+
aws: options.aws,
|
|
456
|
+
});
|
|
317
457
|
const pluginBlocks = await collectPluginBlocks(plugins, terminal, logger);
|
|
318
458
|
const rendered = renderConfig({
|
|
319
459
|
region: region,
|
|
@@ -321,6 +461,7 @@ export async function initSite(fs, terminal, logger, plugins, root) {
|
|
|
321
461
|
domain,
|
|
322
462
|
githubRepo,
|
|
323
463
|
ssr,
|
|
464
|
+
aws: { profile, accountId },
|
|
324
465
|
pluginBlocks,
|
|
325
466
|
});
|
|
326
467
|
// Re-parsed before it is trusted onto disk, mirroring `plugin-commands.ts`'s
|
package/dist/known-commands.d.ts
CHANGED
|
@@ -15,9 +15,8 @@
|
|
|
15
15
|
/**
|
|
16
16
|
* The CLI's command-name registries, isolated in their own leaf module with
|
|
17
17
|
* no imports of its own. Both `cli.ts` (the dispatcher - it pulls in every
|
|
18
|
-
* built-in command implementation, and
|
|
19
|
-
*
|
|
20
|
-
* post-deploy sync `commands.ts` imports) and
|
|
18
|
+
* built-in command implementation, and no plugin package by name - pds
|
|
19
|
+
* reaches `deploy` only through its `afterDeploy` hook) and
|
|
21
20
|
* `plugins.ts` (a domain module that must stay inside the port boundary -
|
|
22
21
|
* see DEVELOPMENT.md §Hexagonal architecture) need to read the same set of
|
|
23
22
|
* reserved names, and neither may import the other: `plugins.ts` importing
|
|
@@ -27,10 +26,10 @@
|
|
|
27
26
|
* other to finish initialising before either can run. This module gives
|
|
28
27
|
* both callers a shared, dependency-free home instead.
|
|
29
28
|
*
|
|
30
|
-
* `KNOWN_COMMANDS` is the
|
|
31
|
-
*
|
|
32
|
-
* `bootstrap`, `deploy`, `
|
|
33
|
-
* `status
|
|
29
|
+
* `KNOWN_COMMANDS` is the names `cli.ts`'s `main` dispatches through its
|
|
30
|
+
* `switch`, after the `KNOWN_COMMANDS.has(command)` membership test:
|
|
31
|
+
* `bootstrap`, `deploy`, `stage`, `promote`, `rollback`, `delete`, `destroy`,
|
|
32
|
+
* `history`, `logs`, `status`, `verify` - plus `plugin`, which `main` claims before the switch.
|
|
34
33
|
*
|
|
35
34
|
* `RESERVED_COMMANDS` is every name a plugin may never claim as its own -
|
|
36
35
|
* see `discover`'s namespace-collision check in `plugins.ts`. It is
|
|
@@ -43,12 +42,15 @@
|
|
|
43
42
|
* `KNOWN_COMMANDS`), but the name is reserved from the moment any plugin
|
|
44
43
|
* could collide with it, and the union keeps this set correct both before
|
|
45
44
|
* and after that command exists - no second edit required either way.
|
|
45
|
+
* `whoami` is named explicitly too: like `init` it is dispatched ahead of the
|
|
46
|
+
* membership test, because it builds no context.
|
|
46
47
|
*
|
|
47
48
|
* `pds` is deliberately absent from `RESERVED_COMMANDS`, and adding it here
|
|
48
49
|
* would break `blogwright pds` outright. There is no built-in `pds` command:
|
|
49
50
|
* task 29 deleted `cli.ts`'s hardcoded `command === 'pds'` branch, and the
|
|
50
|
-
* namespace is now served by the
|
|
51
|
-
* declares the plugin name `pds` and is
|
|
51
|
+
* namespace is now served by the `blogwright-pds` package a site installs
|
|
52
|
+
* (`blogwright plugin add pds`), which declares the plugin name `pds` and is
|
|
53
|
+
* discovered like any other plugin.
|
|
52
54
|
* Reserving the name would make `discover`'s reserved-name check
|
|
53
55
|
* (`plugins.ts`) reject that package - a load `failures` entry, never an
|
|
54
56
|
* installed plugin - so `blogwright pds <action>` would exit 1 with `no
|
package/dist/known-commands.js
CHANGED
|
@@ -15,9 +15,8 @@
|
|
|
15
15
|
/**
|
|
16
16
|
* The CLI's command-name registries, isolated in their own leaf module with
|
|
17
17
|
* no imports of its own. Both `cli.ts` (the dispatcher - it pulls in every
|
|
18
|
-
* built-in command implementation, and
|
|
19
|
-
*
|
|
20
|
-
* post-deploy sync `commands.ts` imports) and
|
|
18
|
+
* built-in command implementation, and no plugin package by name - pds
|
|
19
|
+
* reaches `deploy` only through its `afterDeploy` hook) and
|
|
21
20
|
* `plugins.ts` (a domain module that must stay inside the port boundary -
|
|
22
21
|
* see DEVELOPMENT.md §Hexagonal architecture) need to read the same set of
|
|
23
22
|
* reserved names, and neither may import the other: `plugins.ts` importing
|
|
@@ -27,10 +26,10 @@
|
|
|
27
26
|
* other to finish initialising before either can run. This module gives
|
|
28
27
|
* both callers a shared, dependency-free home instead.
|
|
29
28
|
*
|
|
30
|
-
* `KNOWN_COMMANDS` is the
|
|
31
|
-
*
|
|
32
|
-
* `bootstrap`, `deploy`, `
|
|
33
|
-
* `status
|
|
29
|
+
* `KNOWN_COMMANDS` is the names `cli.ts`'s `main` dispatches through its
|
|
30
|
+
* `switch`, after the `KNOWN_COMMANDS.has(command)` membership test:
|
|
31
|
+
* `bootstrap`, `deploy`, `stage`, `promote`, `rollback`, `delete`, `destroy`,
|
|
32
|
+
* `history`, `logs`, `status`, `verify` - plus `plugin`, which `main` claims before the switch.
|
|
34
33
|
*
|
|
35
34
|
* `RESERVED_COMMANDS` is every name a plugin may never claim as its own -
|
|
36
35
|
* see `discover`'s namespace-collision check in `plugins.ts`. It is
|
|
@@ -43,12 +42,15 @@
|
|
|
43
42
|
* `KNOWN_COMMANDS`), but the name is reserved from the moment any plugin
|
|
44
43
|
* could collide with it, and the union keeps this set correct both before
|
|
45
44
|
* and after that command exists - no second edit required either way.
|
|
45
|
+
* `whoami` is named explicitly too: like `init` it is dispatched ahead of the
|
|
46
|
+
* membership test, because it builds no context.
|
|
46
47
|
*
|
|
47
48
|
* `pds` is deliberately absent from `RESERVED_COMMANDS`, and adding it here
|
|
48
49
|
* would break `blogwright pds` outright. There is no built-in `pds` command:
|
|
49
50
|
* task 29 deleted `cli.ts`'s hardcoded `command === 'pds'` branch, and the
|
|
50
|
-
* namespace is now served by the
|
|
51
|
-
* declares the plugin name `pds` and is
|
|
51
|
+
* namespace is now served by the `blogwright-pds` package a site installs
|
|
52
|
+
* (`blogwright plugin add pds`), which declares the plugin name `pds` and is
|
|
53
|
+
* discovered like any other plugin.
|
|
52
54
|
* Reserving the name would make `discover`'s reserved-name check
|
|
53
55
|
* (`plugins.ts`) reject that package - a load `failures` entry, never an
|
|
54
56
|
* installed plugin - so `blogwright pds <action>` would exit 1 with `no
|
|
@@ -62,12 +64,15 @@
|
|
|
62
64
|
export const KNOWN_COMMANDS = new Set([
|
|
63
65
|
'bootstrap',
|
|
64
66
|
'deploy',
|
|
67
|
+
'stage',
|
|
68
|
+
'promote',
|
|
65
69
|
'rollback',
|
|
66
70
|
'delete',
|
|
67
71
|
'destroy',
|
|
68
72
|
'history',
|
|
69
73
|
'logs',
|
|
70
74
|
'status',
|
|
75
|
+
'verify',
|
|
71
76
|
'plugin',
|
|
72
77
|
]);
|
|
73
78
|
export const RESERVED_COMMANDS = new Set([
|
|
@@ -75,4 +80,5 @@ export const RESERVED_COMMANDS = new Set([
|
|
|
75
80
|
'init',
|
|
76
81
|
'preview',
|
|
77
82
|
'plugin',
|
|
83
|
+
'whoami',
|
|
78
84
|
]);
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The live-release record (`build/live-release.json`): which recorded release
|
|
3
|
+
* the last deploy, promote or rollback published to `site/`, so the next
|
|
4
|
+
* promotion can name the release it replaces. It records what blogwright did,
|
|
5
|
+
* not what S3 holds - `blogwright verify` is the reading of S3.
|
|
6
|
+
*
|
|
7
|
+
* Before a command starts changing `site/` it marks the record `publishing`,
|
|
8
|
+
* keeping the release it replaces as `previous`, and only a command that
|
|
9
|
+
* finished turns it back into a live release. A command that stops partway
|
|
10
|
+
* therefore leaves "a publish of X stopped partway", never the old release's
|
|
11
|
+
* name over a `site/` that no longer holds it.
|
|
12
|
+
*/
|
|
13
|
+
import type { ArtifactManifest } from 'blogwright-core';
|
|
14
|
+
import type { OpsContext } from './context.js';
|
|
15
|
+
export declare const LIVE_RELEASE_KEY = "build/live-release.json";
|
|
16
|
+
/** The command that published a live release, or emptied `site/`. */
|
|
17
|
+
export type LiveReleaseSource = 'deploy' | 'promote' | 'rollback' | 'delete';
|
|
18
|
+
/** A release a command finished publishing to `site/`. */
|
|
19
|
+
interface LiveRelease {
|
|
20
|
+
hash: string;
|
|
21
|
+
release: string;
|
|
22
|
+
releaseHash: string;
|
|
23
|
+
publishedAt: string;
|
|
24
|
+
via: LiveReleaseSource;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* A command is changing `site/`, or stopped partway through changing it: what
|
|
28
|
+
* `site/` holds is unknown until a command finishes.
|
|
29
|
+
*/
|
|
30
|
+
interface PublishingLiveRelease {
|
|
31
|
+
status: 'publishing';
|
|
32
|
+
/** The revision being published; absent when `site/` is being emptied. */
|
|
33
|
+
hash?: string | undefined;
|
|
34
|
+
via: LiveReleaseSource;
|
|
35
|
+
startedAt: string;
|
|
36
|
+
/** The last release a command finished publishing before this one began. */
|
|
37
|
+
previous?: LiveRelease | undefined;
|
|
38
|
+
}
|
|
39
|
+
export type LiveReleaseRecord = LiveRelease | PublishingLiveRelease;
|
|
40
|
+
/** Whether a record names a release a command finished publishing. */
|
|
41
|
+
export declare function isSettledLiveRelease(record: LiveReleaseRecord | undefined): record is LiveRelease;
|
|
42
|
+
/**
|
|
43
|
+
* The live-release record, or undefined when none is recorded. The record is
|
|
44
|
+
* informational, so an unreadable one is reported and treated as absent
|
|
45
|
+
* rather than failing the command that wanted to name it.
|
|
46
|
+
*/
|
|
47
|
+
export declare function readLiveRelease(ctx: OpsContext): Promise<LiveReleaseRecord | undefined>;
|
|
48
|
+
/**
|
|
49
|
+
* Mark `site/` as changing before a command touches it. The release it
|
|
50
|
+
* replaces is kept as `previous` - carried over from an earlier publish that
|
|
51
|
+
* stopped partway, so it always names the last release a command finished.
|
|
52
|
+
*/
|
|
53
|
+
export declare function markLiveReleasePublishing(ctx: OpsContext, hash: string | undefined, via: LiveReleaseSource): Promise<void>;
|
|
54
|
+
/** Record that `manifest`'s release is now what `site/` holds. */
|
|
55
|
+
export declare function recordLiveRelease(ctx: OpsContext, manifest: ArtifactManifest, via: LiveReleaseSource): Promise<void>;
|
|
56
|
+
/** Drop the record when `site/` changed in a way no artifact manifest describes. */
|
|
57
|
+
export declare function forgetLiveRelease(ctx: OpsContext): Promise<void>;
|
|
58
|
+
/** One line naming the live release, for a before/after report. */
|
|
59
|
+
export declare function describeLiveRelease(live: LiveReleaseRecord | undefined): string;
|
|
60
|
+
/** How many publications a revision's record keeps - the newest ones. */
|
|
61
|
+
export declare const PUBLISHED_RELEASES_KEPT = 50;
|
|
62
|
+
/** One publication of a staged release into `site/`. */
|
|
63
|
+
export interface ReleasePublication {
|
|
64
|
+
release: string;
|
|
65
|
+
releaseHash: string;
|
|
66
|
+
via: Extract<LiveReleaseSource, 'promote' | 'rollback'>;
|
|
67
|
+
publishedAt: string;
|
|
68
|
+
}
|
|
69
|
+
export declare function publishedReleasesKey(hash: string): string;
|
|
70
|
+
/**
|
|
71
|
+
* A revision's publications, oldest first; empty when none is recorded. Like
|
|
72
|
+
* the live-release record it is informational, so an unreadable one is
|
|
73
|
+
* reported and read as empty.
|
|
74
|
+
*/
|
|
75
|
+
export declare function readPublications(ctx: OpsContext, hash: string): Promise<ReleasePublication[]>;
|
|
76
|
+
/** Append a publication of `manifest`'s release to its revision's record. */
|
|
77
|
+
export declare function recordPublication(ctx: OpsContext, manifest: ArtifactManifest, via: ReleasePublication['via']): Promise<void>;
|
|
78
|
+
export {};
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The live-release record (`build/live-release.json`): which recorded release
|
|
3
|
+
* the last deploy, promote or rollback published to `site/`, so the next
|
|
4
|
+
* promotion can name the release it replaces. It records what blogwright did,
|
|
5
|
+
* not what S3 holds - `blogwright verify` is the reading of S3.
|
|
6
|
+
*
|
|
7
|
+
* Before a command starts changing `site/` it marks the record `publishing`,
|
|
8
|
+
* keeping the release it replaces as `previous`, and only a command that
|
|
9
|
+
* finished turns it back into a live release. A command that stops partway
|
|
10
|
+
* therefore leaves "a publish of X stopped partway", never the old release's
|
|
11
|
+
* name over a `site/` that no longer holds it.
|
|
12
|
+
*/
|
|
13
|
+
export const LIVE_RELEASE_KEY = 'build/live-release.json';
|
|
14
|
+
function isRecordObject(value) {
|
|
15
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
16
|
+
}
|
|
17
|
+
function isLiveRelease(value) {
|
|
18
|
+
if (!isRecordObject(value) || value.status !== undefined)
|
|
19
|
+
return false;
|
|
20
|
+
return ['hash', 'release', 'releaseHash', 'publishedAt', 'via'].every((field) => typeof value[field] === 'string');
|
|
21
|
+
}
|
|
22
|
+
function isPublishing(value) {
|
|
23
|
+
if (!isRecordObject(value) || value.status !== 'publishing')
|
|
24
|
+
return false;
|
|
25
|
+
return (typeof value.via === 'string' &&
|
|
26
|
+
typeof value.startedAt === 'string' &&
|
|
27
|
+
(value.hash === undefined || typeof value.hash === 'string') &&
|
|
28
|
+
(value.previous === undefined || isLiveRelease(value.previous)));
|
|
29
|
+
}
|
|
30
|
+
/** Whether a record names a release a command finished publishing. */
|
|
31
|
+
export function isSettledLiveRelease(record) {
|
|
32
|
+
return record !== undefined && !('status' in record);
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* The live-release record, or undefined when none is recorded. The record is
|
|
36
|
+
* informational, so an unreadable one is reported and treated as absent
|
|
37
|
+
* rather than failing the command that wanted to name it.
|
|
38
|
+
*/
|
|
39
|
+
export async function readLiveRelease(ctx) {
|
|
40
|
+
const text = await ctx.clients.s3.getObjectText(ctx.names.bucket, LIVE_RELEASE_KEY);
|
|
41
|
+
if (text === undefined)
|
|
42
|
+
return undefined;
|
|
43
|
+
let parsed;
|
|
44
|
+
try {
|
|
45
|
+
parsed = JSON.parse(text);
|
|
46
|
+
}
|
|
47
|
+
catch {
|
|
48
|
+
parsed = undefined;
|
|
49
|
+
}
|
|
50
|
+
if (isLiveRelease(parsed) || isPublishing(parsed))
|
|
51
|
+
return parsed;
|
|
52
|
+
ctx.logger.warn(`ignoring unreadable live-release record s3://${ctx.names.bucket}/${LIVE_RELEASE_KEY}`);
|
|
53
|
+
return undefined;
|
|
54
|
+
}
|
|
55
|
+
async function writeLiveRelease(ctx, record) {
|
|
56
|
+
await ctx.clients.s3.putObject(ctx.names.bucket, LIVE_RELEASE_KEY, JSON.stringify(record, null, 2), 'application/json');
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Mark `site/` as changing before a command touches it. The release it
|
|
60
|
+
* replaces is kept as `previous` - carried over from an earlier publish that
|
|
61
|
+
* stopped partway, so it always names the last release a command finished.
|
|
62
|
+
*/
|
|
63
|
+
export async function markLiveReleasePublishing(ctx, hash, via) {
|
|
64
|
+
const current = await readLiveRelease(ctx);
|
|
65
|
+
const previous = isSettledLiveRelease(current) ? current : current?.previous;
|
|
66
|
+
await writeLiveRelease(ctx, {
|
|
67
|
+
status: 'publishing',
|
|
68
|
+
...(hash ? { hash } : {}),
|
|
69
|
+
via,
|
|
70
|
+
startedAt: new Date().toISOString(),
|
|
71
|
+
...(previous ? { previous } : {}),
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
/** Record that `manifest`'s release is now what `site/` holds. */
|
|
75
|
+
export async function recordLiveRelease(ctx, manifest, via) {
|
|
76
|
+
await writeLiveRelease(ctx, {
|
|
77
|
+
hash: manifest.hash,
|
|
78
|
+
release: manifest.release,
|
|
79
|
+
releaseHash: manifest.releaseHash,
|
|
80
|
+
publishedAt: new Date().toISOString(),
|
|
81
|
+
via,
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
/** Drop the record when `site/` changed in a way no artifact manifest describes. */
|
|
85
|
+
export async function forgetLiveRelease(ctx) {
|
|
86
|
+
await ctx.clients.s3.deleteObject(ctx.names.bucket, LIVE_RELEASE_KEY);
|
|
87
|
+
}
|
|
88
|
+
/** One line naming the live release, for a before/after report. */
|
|
89
|
+
export function describeLiveRelease(live) {
|
|
90
|
+
if (live === undefined) {
|
|
91
|
+
return ('unknown - no live-release record: site/ was last published before blogwright ' +
|
|
92
|
+
'recorded releases, by a build that recorded no artifact manifest, or not at all');
|
|
93
|
+
}
|
|
94
|
+
if (isSettledLiveRelease(live))
|
|
95
|
+
return `${live.release} (sha256 ${live.releaseHash})`;
|
|
96
|
+
const what = live.hash ? `a ${live.via} of ${live.hash}` : `a ${live.via}`;
|
|
97
|
+
const before = live.previous
|
|
98
|
+
? `; the last completed release was ${live.previous.release} (sha256 ${live.previous.releaseHash})`
|
|
99
|
+
: '';
|
|
100
|
+
return `unknown (${what} started ${live.startedAt} did not finish${before})`;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Every staged release a `promote` or a republishing `rollback` published for
|
|
104
|
+
* a revision (`build/published/<hash>.json`), oldest first. `stage` never
|
|
105
|
+
* writes it, so it outlives a re-stage of the same revision: the record of
|
|
106
|
+
* what was actually live is kept even after the staged bytes are replaced.
|
|
107
|
+
*/
|
|
108
|
+
const PUBLISHED_RELEASES_PREFIX = 'build/published/';
|
|
109
|
+
/** How many publications a revision's record keeps - the newest ones. */
|
|
110
|
+
export const PUBLISHED_RELEASES_KEPT = 50;
|
|
111
|
+
export function publishedReleasesKey(hash) {
|
|
112
|
+
return `${PUBLISHED_RELEASES_PREFIX}${hash}.json`;
|
|
113
|
+
}
|
|
114
|
+
function isPublication(value) {
|
|
115
|
+
return (isRecordObject(value) &&
|
|
116
|
+
['release', 'releaseHash', 'via', 'publishedAt'].every((field) => typeof value[field] === 'string'));
|
|
117
|
+
}
|
|
118
|
+
function isPublishedReleases(value) {
|
|
119
|
+
return (isRecordObject(value) &&
|
|
120
|
+
typeof value.hash === 'string' &&
|
|
121
|
+
Array.isArray(value.publications) &&
|
|
122
|
+
value.publications.every(isPublication));
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* A revision's publications, oldest first; empty when none is recorded. Like
|
|
126
|
+
* the live-release record it is informational, so an unreadable one is
|
|
127
|
+
* reported and read as empty.
|
|
128
|
+
*/
|
|
129
|
+
export async function readPublications(ctx, hash) {
|
|
130
|
+
const key = publishedReleasesKey(hash);
|
|
131
|
+
const text = await ctx.clients.s3.getObjectText(ctx.names.bucket, key);
|
|
132
|
+
if (text === undefined)
|
|
133
|
+
return [];
|
|
134
|
+
let parsed;
|
|
135
|
+
try {
|
|
136
|
+
parsed = JSON.parse(text);
|
|
137
|
+
}
|
|
138
|
+
catch {
|
|
139
|
+
parsed = undefined;
|
|
140
|
+
}
|
|
141
|
+
if (isPublishedReleases(parsed) && parsed.hash === hash)
|
|
142
|
+
return parsed.publications;
|
|
143
|
+
ctx.logger.warn(`ignoring unreadable publication record s3://${ctx.names.bucket}/${key}`);
|
|
144
|
+
return [];
|
|
145
|
+
}
|
|
146
|
+
/** Append a publication of `manifest`'s release to its revision's record. */
|
|
147
|
+
export async function recordPublication(ctx, manifest, via) {
|
|
148
|
+
const publications = [
|
|
149
|
+
...(await readPublications(ctx, manifest.hash)),
|
|
150
|
+
{
|
|
151
|
+
release: manifest.release,
|
|
152
|
+
releaseHash: manifest.releaseHash,
|
|
153
|
+
via,
|
|
154
|
+
publishedAt: new Date().toISOString(),
|
|
155
|
+
},
|
|
156
|
+
].slice(-PUBLISHED_RELEASES_KEPT);
|
|
157
|
+
const record = { hash: manifest.hash, publications };
|
|
158
|
+
await ctx.clients.s3.putObject(ctx.names.bucket, publishedReleasesKey(manifest.hash), JSON.stringify(record, null, 2), 'application/json');
|
|
159
|
+
}
|
package/dist/lock.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The environment lock (`build/lock.json`): one command at a time may write
|
|
3
|
+
* an environment's live `site/` or its live-release record. `deploy`,
|
|
4
|
+
* `rollback`, `stage`, `promote` and `delete` take it before they change
|
|
5
|
+
* anything and release it when they finish, failed or not, so two of them can
|
|
6
|
+
* never interleave their writes - a deploy's builder listing `site/` while a
|
|
7
|
+
* promotion copies into it, or two deploys racing for the same objects.
|
|
8
|
+
*
|
|
9
|
+
* The lock is a conditional PUT (`If-None-Match: *`), so exactly one caller
|
|
10
|
+
* creates it. A command that dies without releasing it - a killed CI job, a
|
|
11
|
+
* closed laptop - leaves it behind; the next command refuses, naming who held
|
|
12
|
+
* it, for what and since when, and `--force-unlock` replaces it once that
|
|
13
|
+
* holder is known to be gone. Nothing expires it on a timer: a long build is
|
|
14
|
+
* indistinguishable from a dead one, and guessing wrong would re-open the race.
|
|
15
|
+
*/
|
|
16
|
+
import type { OpsContext } from './context.js';
|
|
17
|
+
/** Where an environment's lock lives - outside every builder grant. */
|
|
18
|
+
export declare const ENV_LOCK_KEY = "build/lock.json";
|
|
19
|
+
/** Who holds an environment's lock, and for what. */
|
|
20
|
+
export interface EnvLock {
|
|
21
|
+
/** Unique per acquisition: release deletes the lock only while it is still this one. */
|
|
22
|
+
id: string;
|
|
23
|
+
/** The AWS identity (`sts:GetCallerIdentity` ARN) that took it. */
|
|
24
|
+
holder: string;
|
|
25
|
+
/** The command that took it, e.g. `promote`. */
|
|
26
|
+
command: string;
|
|
27
|
+
/** The revision the command is publishing, when it has one. */
|
|
28
|
+
hash?: string | undefined;
|
|
29
|
+
/** When it was taken (ISO-8601). */
|
|
30
|
+
startedAt: string;
|
|
31
|
+
}
|
|
32
|
+
export interface LockOptions {
|
|
33
|
+
/** Replace a lock left behind by a command that is no longer running. */
|
|
34
|
+
forceUnlock?: boolean | undefined;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Take the environment's lock for `command`, or throw naming whoever holds
|
|
38
|
+
* it. With `forceUnlock`, a held lock is first removed, with a warning.
|
|
39
|
+
*/
|
|
40
|
+
export declare function acquireEnvLock(ctx: OpsContext, command: string, hash: string | undefined, opts?: LockOptions): Promise<EnvLock>;
|
|
41
|
+
/**
|
|
42
|
+
* Release `lock` if it is still the one held. A lock replaced by
|
|
43
|
+
* `--force-unlock` belongs to someone else now and is left alone. Never
|
|
44
|
+
* throws: the command's own outcome must not be masked by its cleanup.
|
|
45
|
+
*/
|
|
46
|
+
export declare function releaseEnvLock(ctx: OpsContext, lock: EnvLock): Promise<void>;
|
|
47
|
+
/** Run `fn` holding the environment's lock, releasing it however `fn` ends. */
|
|
48
|
+
export declare function withEnvLock<T>(ctx: OpsContext, command: string, hash: string | undefined, opts: LockOptions, fn: () => Promise<T>): Promise<T>;
|
|
49
|
+
/** Refuse when the environment is locked - for `destroy`, which removes the lock with the bucket. */
|
|
50
|
+
export declare function assertEnvUnlocked(ctx: OpsContext, command: string, opts?: LockOptions): Promise<void>;
|