castle-web-cli 0.4.225 → 0.4.227

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/dist/save-deck.js CHANGED
@@ -11,6 +11,8 @@ import { selectSaveCover } from './saveCover.js';
11
11
  import { COVER_FILE } from './localPaths.js';
12
12
  import { buildServerBundle } from './serverBundle.js';
13
13
  import { decideSavePrecondition, EXIT_SAVED_DECK_NEWER, fetchServerSourceVersion, readSyncMarker, saveRefusedLine, saveRefusedMessage, WEB_DECK_SOURCE_STALE_CODE, writeSyncMarker, } from './webSourceSync.js';
14
+ import { DeckTooLargeError, MAX_SCENE_DATA_BYTES, MAX_SOURCE_ARCHIVE_BYTES, SAVE_FAILURE_ENV, classifySaveFailure, saveFailedLine, sceneTooLargeMessage, sourceTooLargeMessage, } from './saveFailure.js';
15
+ export { DeckTooLargeError, MAX_SCENE_DATA_BYTES, MAX_SOURCE_ARCHIVE_BYTES, sceneTooLargeMessage, sourceTooLargeMessage, } from './saveFailure.js';
14
16
  // `imports/` is derived state like node_modules: a dependency's files belong to
15
17
  // the deck that published them, and castle.json's import pins are enough to fetch
16
18
  // them again -- so they neither bloat this deck's archive nor get republished as
@@ -23,6 +25,9 @@ export const SOURCE_ARCHIVE_EXCLUDES = ['node_modules', 'dist', '.castle', '.git
23
25
  // independently deployable.
24
26
  export const SAVE_STAGE_TELEMETRY_PREFIX = 'CASTLE_SAVE_TELEMETRY ';
25
27
  export const SAVE_COVER_SELECTION_TELEMETRY_PREFIX = 'CASTLE_SAVE_COVER_SELECTION ';
28
+ // Long enough to move a payload at either cap over a slow uplink (100 MB at ~3 Mbit/s).
29
+ const LARGE_UPLOAD_TIMEOUT_MS = 300_000;
30
+ let failedStage = null;
26
31
  function emitSaveStage(stage, outcome, startedAtMs, fields = {}) {
27
32
  if (process.env.CASTLE_SAVE_STAGE_TELEMETRY !== '1')
28
33
  return;
@@ -45,6 +50,7 @@ async function traceSaveStage(stage, operation, fields) {
45
50
  return result;
46
51
  }
47
52
  catch (error) {
53
+ failedStage = stage;
48
54
  emitSaveStage(stage, 'failure', startedAtMs);
49
55
  throw error;
50
56
  }
@@ -74,6 +80,37 @@ export function runTar(args, opts = {}) {
74
80
  });
75
81
  });
76
82
  }
83
+ // The biggest files the source archive would carry, as a hint for what to shrink. Skips what the
84
+ // archive excludes and never follows a symlink; unreadable entries are left out.
85
+ function largestSourceFiles(projectDir, count) {
86
+ const found = [];
87
+ const walk = (rel) => {
88
+ let entries;
89
+ try {
90
+ entries = fs.readdirSync(path.join(projectDir, rel), { withFileTypes: true });
91
+ }
92
+ catch {
93
+ return;
94
+ }
95
+ for (const entry of entries) {
96
+ const child = rel ? path.join(rel, entry.name) : entry.name;
97
+ if (!rel && SOURCE_ARCHIVE_EXCLUDES.includes(entry.name))
98
+ continue;
99
+ if (entry.isDirectory())
100
+ walk(child);
101
+ else if (entry.isFile()) {
102
+ try {
103
+ found.push({ file: child, bytes: fs.lstatSync(path.join(projectDir, child)).size });
104
+ }
105
+ catch {
106
+ /* vanished mid-walk */
107
+ }
108
+ }
109
+ }
110
+ };
111
+ walk('');
112
+ return found.sort((a, b) => b.bytes - a.bytes).slice(0, count);
113
+ }
77
114
  export async function archiveSource(projectDir) {
78
115
  const tmpFile = path.join(os.tmpdir(), `castle-source-${nanoid(8)}.tar.gz`);
79
116
  const args = ['-czf', tmpFile];
@@ -123,17 +160,57 @@ async function uploadPresignedFile(uploadConfig, file, contentType, timeoutMs, l
123
160
  if (response.status >= 300)
124
161
  throw new Error(`${label} failed: HTTP ${response.status}`);
125
162
  }
163
+ // The source a save uploads, packed (streamed through gzip by tar) and size-checked before
164
+ // anything is published, so the bytes checked are the bytes uploaded. `castleJson` is the
165
+ // castle.json to archive in place of the one on disk: save-deck rewrites that file only after
166
+ // publishing, from the publish result, and the saved source must already carry the new version
167
+ // (a new deck's ids, a new title). The top-level entries are named one by one to leave out only
168
+ // the root castle.json -- an --exclude pattern would also match nested files of that name (bsdtar).
169
+ export async function packSourceForSave(projectDir, castleJson, { published = false } = {}) {
170
+ const stageDir = fs.mkdtempSync(path.join(os.tmpdir(), 'castle-source-'));
171
+ const outFile = path.join(stageDir, 'source.tar.gz');
172
+ try {
173
+ const entries = fs
174
+ .readdirSync(projectDir)
175
+ .filter((name) => !SOURCE_ARCHIVE_EXCLUDES.includes(name))
176
+ .filter((name) => castleJson === null || name !== 'castle.json')
177
+ .sort()
178
+ .map((name) => `./${name}`);
179
+ const args = ['-czf', outFile];
180
+ for (const ex of SOURCE_ARCHIVE_EXCLUDES)
181
+ args.push(`--exclude=./${ex}`);
182
+ // Every name starts with `./`, so none reads as an option.
183
+ args.push('-C', projectDir, ...entries);
184
+ if (castleJson !== null) {
185
+ const castleJsonDir = path.join(stageDir, 'castle-json');
186
+ fs.mkdirSync(castleJsonDir);
187
+ fs.writeFileSync(path.join(castleJsonDir, 'castle.json'), castleJson, 'utf-8');
188
+ // `-C` is positional: it applies to the names after it.
189
+ args.push('-C', castleJsonDir, './castle.json');
190
+ }
191
+ await runTar(args);
192
+ const archive = fs.readFileSync(outFile);
193
+ if (archive.byteLength > MAX_SOURCE_ARCHIVE_BYTES) {
194
+ throw new DeckTooLargeError('source', archive.byteLength, MAX_SOURCE_ARCHIVE_BYTES, sourceTooLargeMessage(archive.byteLength, largestSourceFiles(projectDir, 3), published));
195
+ }
196
+ console.log(`Source archive: ${(archive.length / 1024).toFixed(1)}KB`);
197
+ return archive;
198
+ }
199
+ finally {
200
+ fs.rmSync(stageDir, { recursive: true, force: true });
201
+ }
202
+ }
126
203
  // `expectedS3Key` is the save precondition (api.saveWebDeckSource). Returns the saved source,
127
- // whose key and time become this folder's sync marker.
128
- export async function uploadSource(projectDir, deckId, expectedS3Key) {
129
- const archive = await traceSaveStage('source_archive', () => archiveSource(projectDir), (value) => ({ bytes: value.byteLength }));
130
- const sizeKB = archive.length / 1024;
131
- console.log(`Source archive: ${sizeKB.toFixed(1)}KB`);
204
+ // whose key and time become this folder's sync marker. `archive` is the source save-deck packed
205
+ // before publishing; without it the folder is packed here, as it is on disk.
206
+ export async function uploadSource(projectDir, deckId, expectedS3Key, archive) {
207
+ const source = archive ??
208
+ (await traceSaveStage('source_archive', () => packSourceForSave(projectDir, null, { published: true }), (value) => ({ bytes: value.byteLength })));
132
209
  const uploadConfig = await traceSaveStage('source_upload_config', () => api.createWebDeckSourceUploadConfig(deckId));
133
210
  // FormData expects a Blob; copy the Buffer's bytes so we don't share the underlying ArrayBuffer.
134
- const view = new Uint8Array(archive.byteLength);
135
- view.set(archive);
136
- await traceSaveStage('source_upload', () => uploadPresignedFile(uploadConfig, new Blob([view], { type: 'application/gzip' }), 'application/gzip', 60_000, 'Source upload'));
211
+ const view = new Uint8Array(source.byteLength);
212
+ view.set(source);
213
+ await traceSaveStage('source_upload', () => uploadPresignedFile(uploadConfig, new Blob([view], { type: 'application/gzip' }), 'application/gzip', LARGE_UPLOAD_TIMEOUT_MS, 'Source upload'));
137
214
  return traceSaveStage('source_commit', () => api.saveWebDeckSource(deckId, uploadConfig.uploadId, expectedS3Key));
138
215
  }
139
216
  // Refused: the saved copy is newer than this folder. One machine-readable stdout line (castle-www
@@ -232,6 +309,12 @@ async function uploadLocalCover(projectDir) {
232
309
  return null;
233
310
  }
234
311
  }
312
+ // Preserve any deck-owned config already in castle.json (notably the `editor` block); save-deck
313
+ // only owns the identity fields.
314
+ function castleJsonAfterSave(castleJson, deckId, cardId, title) {
315
+ const next = { ...(castleJson ?? {}), deckId, cardId, title };
316
+ return JSON.stringify(next, null, 2) + '\n';
317
+ }
235
318
  function readCastleJson(dir) {
236
319
  const p = path.join(dir, 'castle.json');
237
320
  if (!fs.existsSync(p))
@@ -273,6 +356,18 @@ export async function saveDeck(dir, opts = {}) {
273
356
  console.error(`No index.html found in ${projectDir}`);
274
357
  process.exit(1);
275
358
  }
359
+ failedStage = null;
360
+ try {
361
+ await saveDeckAfterValidation(dir, opts, projectDir, visibility);
362
+ }
363
+ catch (error) {
364
+ if (process.env[SAVE_FAILURE_ENV] === '1') {
365
+ console.log(saveFailedLine(classifySaveFailure(failedStage, error)));
366
+ }
367
+ throw error;
368
+ }
369
+ }
370
+ async function saveDeckAfterValidation(dir, opts, projectDir, visibility) {
276
371
  const castleJson = readCastleJson(projectDir);
277
372
  const existingDeckId = typeof castleJson?.deckId === 'string' && castleJson.deckId ? castleJson.deckId : null;
278
373
  // A deck without an id is new: the source commit sends no precondition, as before.
@@ -298,10 +393,21 @@ export async function saveDeck(dir, opts = {}) {
298
393
  if (sizeKB > 1024) {
299
394
  console.warn(`Warning: Bundle is ${(sizeKB / 1024).toFixed(1)}MB. Large bundles may load slowly.`);
300
395
  }
301
- const sceneData = buildSceneData(bundle);
396
+ // Both of ghost's size caps are checked here, before anything is uploaded: the deck goes live at
397
+ // content_publish, and the source is uploaded only after that.
398
+ const sceneJson = JSON.stringify(buildSceneData(bundle));
399
+ const sceneBytes = Buffer.byteLength(sceneJson);
400
+ if (sceneBytes > MAX_SCENE_DATA_BYTES) {
401
+ // Reported as the stage that would have failed, so castle-www's failed_at stays comparable.
402
+ await traceSaveStage('scene_upload', () => Promise.reject(new DeckTooLargeError('bundle', sceneBytes, MAX_SCENE_DATA_BYTES, sceneTooLargeMessage(sceneBytes))));
403
+ }
302
404
  const isNew = !castleJson;
303
405
  const cardId = castleJson?.cardId ?? nanoid(12);
304
406
  const deckId = castleJson?.deckId ?? nanoid(12);
407
+ const title = opts.title ?? castleJson?.title ?? path.basename(path.resolve(projectDir));
408
+ // Packed now, from the same files as the bundle, with the castle.json this save will write, and
409
+ // uploaded as is after the deck is published.
410
+ const sourceArchive = await traceSaveStage('source_archive', () => packSourceForSave(projectDir, castleJsonAfterSave(castleJson, deckId, cardId, title)), (value) => ({ bytes: value.byteLength }));
305
411
  // Capturing and uploading the cover depends only on the already-running serve. Start it as
306
412
  // soon as the bundle has passed, while the independent scene upload is being authorized and
307
413
  // transferred. The promise is deliberately non-throwing: a thumbnail must never make the
@@ -320,17 +426,16 @@ export async function saveDeck(dir, opts = {}) {
320
426
  for (const [k, v] of Object.entries(uploadConfig.postFields)) {
321
427
  formData.append(k, String(v));
322
428
  }
323
- formData.append('file', new Blob([JSON.stringify(sceneData)]));
429
+ formData.append('file', new Blob([sceneJson]));
324
430
  await traceSaveStage('scene_upload', async () => {
325
431
  const response = await fetch(uploadConfig.postUrl, {
326
432
  method: 'POST',
327
433
  body: formData,
328
- signal: AbortSignal.timeout(30000),
434
+ signal: AbortSignal.timeout(LARGE_UPLOAD_TIMEOUT_MS),
329
435
  });
330
436
  if (response.status >= 300)
331
437
  throw new Error(`Upload failed: HTTP ${response.status}`);
332
438
  });
333
- const title = opts.title ?? castleJson?.title ?? path.basename(path.resolve(projectDir));
334
439
  const deckInput = { deckId, title };
335
440
  // Omitted unless asked for, or the deck is new and needs one: updateDeckV2
336
441
  // only touches visibility when it is sent, so a deck the creator published
@@ -366,20 +471,12 @@ export async function saveDeck(dir, opts = {}) {
366
471
  castleJson !== null && Object.prototype.hasOwnProperty.call(castleJson, 'characterBundle')
367
472
  ? api.updateCardAndDeckV2(deckInput, cardInput, castleJson?.characterBundle ?? null)
368
473
  : api.updateCardAndDeckV2(deckInput, cardInput));
369
- // Preserve any deck-owned config already in castle.json (notably the
370
- // `editor` block); save-deck only owns the identity fields below.
371
- const newCastleJson = {
372
- ...(castleJson ?? {}),
373
- deckId: result.deckId,
374
- cardId: result.cardId,
375
- title,
376
- };
377
474
  // Only write when the bytes actually move. An identical rewrite still bumps
378
475
  // mtime, which the serve's watcher reports as a change like any other -- so
379
476
  // a push that changed nothing here would flip the Play panel to "Changes
380
477
  // available" and put castle.json in the next saved version's diff.
381
478
  const castleJsonPath = path.join(projectDir, 'castle.json');
382
- const nextCastleJson = JSON.stringify(newCastleJson, null, 2) + '\n';
479
+ const nextCastleJson = castleJsonAfterSave(castleJson, result.deckId, result.cardId, title);
383
480
  const onDisk = fs.existsSync(castleJsonPath)
384
481
  ? fs.readFileSync(castleJsonPath, 'utf-8')
385
482
  : null;
@@ -406,7 +503,10 @@ export async function saveDeck(dir, opts = {}) {
406
503
  }
407
504
  console.log('Uploading source archive...');
408
505
  // The precondition only applies to the deck it was checked against.
409
- const saved = await uploadSource(projectDir, result.deckId, result.deckId === existingDeckId ? expectedS3Key : undefined);
506
+ const saved = await uploadSource(projectDir, result.deckId, result.deckId === existingDeckId ? expectedS3Key : undefined,
507
+ // Ghost keeps the ids it is sent, so this is the castle.json packed above; if it ever
508
+ // assigned others, the folder is packed again with the file as written.
509
+ result.deckId === deckId && result.cardId === cardId ? sourceArchive : undefined);
410
510
  console.log('Source archive saved.');
411
511
  try {
412
512
  writeSyncMarker(projectDir, result.deckId, saved, markerVia);
@@ -0,0 +1,26 @@
1
+ export declare const MAX_SCENE_DATA_BYTES: number;
2
+ export declare const MAX_SOURCE_ARCHIVE_BYTES: number;
3
+ export declare const SAVE_FAILED_PREFIX = "CASTLE_SAVE_FAILED ";
4
+ export declare const SAVE_FAILURE_ENV = "CASTLE_SAVE_FAILURE_REPORT";
5
+ export type SaveFailureReason = 'too_large' | 'upload_timeout' | 'network' | 'build' | 'unknown';
6
+ export interface SaveFailure {
7
+ reason: SaveFailureReason;
8
+ stage?: string;
9
+ part?: 'bundle' | 'source';
10
+ bytes?: number;
11
+ limitBytes?: number;
12
+ }
13
+ export declare function sceneTooLargeMessage(bytes: number): string;
14
+ export declare function sourceTooLargeMessage(bytes: number, largest: {
15
+ file: string;
16
+ bytes: number;
17
+ }[], published?: boolean): string;
18
+ export declare class DeckTooLargeError extends Error {
19
+ readonly part: 'bundle' | 'source';
20
+ readonly bytes: number;
21
+ readonly limitBytes: number;
22
+ readonly name = "DeckTooLargeError";
23
+ constructor(part: 'bundle' | 'source', bytes: number, limitBytes: number, message: string);
24
+ }
25
+ export declare function classifySaveFailure(stage: string | null, error: unknown): SaveFailure;
26
+ export declare function saveFailedLine(failure: SaveFailure): string;
@@ -0,0 +1,102 @@
1
+ // Ghost's upload ceilings, enforced by S3 in the presigned POST policies (diy.ts
2
+ // MAX_SCENE_DATA_BYTES, webDeckSource.ts MAX_ARCHIVE_BYTES). Mirrored here so an oversized deck
3
+ // is refused before anything is uploaded: past the cap S3 answers only an opaque HTTP 400, and the
4
+ // source upload runs after the deck has already gone live. Keep these in step with ghost.
5
+ export const MAX_SCENE_DATA_BYTES = 50 * 1024 * 1024;
6
+ export const MAX_SOURCE_ARCHIVE_BYTES = 100 * 1024 * 1024;
7
+ export const SAVE_FAILED_PREFIX = 'CASTLE_SAVE_FAILED ';
8
+ export const SAVE_FAILURE_ENV = 'CASTLE_SAVE_FAILURE_REPORT';
9
+ function formatMB(bytes) {
10
+ return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
11
+ }
12
+ export function sceneTooLargeMessage(bytes) {
13
+ return (`This deck is too large to save: its game bundle is ${formatMB(bytes)}, and Castle accepts at ` +
14
+ `most ${formatMB(MAX_SCENE_DATA_BYTES)}. Nothing was published. Images, audio and models are ` +
15
+ 'packed into the bundle, so shrink or remove the largest assets and save again.');
16
+ }
17
+ export function sourceTooLargeMessage(bytes, largest, published = false) {
18
+ const list = largest.map((file) => `${file.file} (${formatMB(file.bytes)})`).join(', ');
19
+ return (`This deck's source is too large to save: compressed, it is ${formatMB(bytes)}, and Castle ` +
20
+ `accepts at most ${formatMB(MAX_SOURCE_ARCHIVE_BYTES)}. ` +
21
+ (published
22
+ ? 'The playable deck was updated, but its source was not saved.'
23
+ : 'Nothing was published.') +
24
+ (list ? ` Largest files: ${list}.` : '') +
25
+ ' Remove or shrink files the deck does not need and save again.');
26
+ }
27
+ export class DeckTooLargeError extends Error {
28
+ part;
29
+ bytes;
30
+ limitBytes;
31
+ name = 'DeckTooLargeError';
32
+ constructor(part, bytes, limitBytes, message) {
33
+ super(message);
34
+ this.part = part;
35
+ this.bytes = bytes;
36
+ this.limitBytes = limitBytes;
37
+ }
38
+ }
39
+ function errorCause(error) {
40
+ return typeof error === 'object' && error !== null && 'cause' in error
41
+ ? error.cause
42
+ : undefined;
43
+ }
44
+ function errorName(error) {
45
+ return typeof error === 'object' && error !== null && 'name' in error
46
+ ? error.name
47
+ : undefined;
48
+ }
49
+ function errorCode(error) {
50
+ return typeof error === 'object' && error !== null && 'code' in error
51
+ ? error.code
52
+ : undefined;
53
+ }
54
+ function withStage(reason, stage) {
55
+ return { reason, ...(stage === null ? {} : { stage }) };
56
+ }
57
+ export function classifySaveFailure(stage, error) {
58
+ if (error instanceof DeckTooLargeError) {
59
+ return {
60
+ ...withStage('too_large', stage),
61
+ part: error.part,
62
+ bytes: error.bytes,
63
+ limitBytes: error.limitBytes,
64
+ };
65
+ }
66
+ if (stage === 'bundle')
67
+ return withStage('build', stage);
68
+ const errors = [error, errorCause(error)];
69
+ if (errors.some((candidate) => {
70
+ const name = errorName(candidate);
71
+ return name === 'TimeoutError' || name === 'AbortError';
72
+ })) {
73
+ return withStage('upload_timeout', stage);
74
+ }
75
+ const networkCodes = new Set([
76
+ 'ECONNRESET',
77
+ 'ECONNREFUSED',
78
+ 'ENOTFOUND',
79
+ 'EAI_AGAIN',
80
+ 'ETIMEDOUT',
81
+ 'EPIPE',
82
+ ]);
83
+ const fetchFailed = errors.some((candidate) => candidate instanceof TypeError && candidate.message === 'fetch failed');
84
+ const codedNetworkFailure = errors.some((candidate) => {
85
+ const code = errorCode(candidate);
86
+ return typeof code === 'string' && (networkCodes.has(code) || code.startsWith('UND_ERR_'));
87
+ });
88
+ if (fetchFailed || codedNetworkFailure)
89
+ return withStage('network', stage);
90
+ return withStage('unknown', stage);
91
+ }
92
+ export function saveFailedLine(failure) {
93
+ return (SAVE_FAILED_PREFIX +
94
+ JSON.stringify({
95
+ event: 'castle_web_save_failed',
96
+ reason: failure.reason,
97
+ ...(failure.stage === undefined ? {} : { stage: failure.stage }),
98
+ ...(failure.part === undefined ? {} : { part: failure.part }),
99
+ ...(failure.bytes === undefined ? {} : { bytes: failure.bytes }),
100
+ ...(failure.limitBytes === undefined ? {} : { limitBytes: failure.limitBytes }),
101
+ }));
102
+ }