@crombolo/transfer 0.34.0 → 0.36.2

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crombolo/transfer",
3
- "version": "0.34.0",
3
+ "version": "0.36.2",
4
4
  "description": "Internal to crombolo, with no compatibility promise: use @crombolo/crombolo. Content transfer for crombolo: bundles of content moved between environments.",
5
5
  "license": "MIT",
6
6
  "author": "Crombolo",
@@ -28,7 +28,7 @@
28
28
  "access": "public"
29
29
  },
30
30
  "dependencies": {
31
- "@crombolo/core": "0.34.0",
32
- "@crombolo/data": "0.34.0"
31
+ "@crombolo/core": "0.36.2",
32
+ "@crombolo/data": "0.36.2"
33
33
  }
34
34
  }
package/src/export.ts CHANGED
@@ -10,7 +10,7 @@
10
10
  * carries its draft and says so. `--drafts` takes the current draft throughout,
11
11
  * for the case where the point is to move work in progress.
12
12
  */
13
- import type { DocumentAggregate, DocumentValue } from '@crombolo/core'
13
+ import type { DocumentAggregate, DocumentValue, MediaItemAccess } from '@crombolo/core'
14
14
  import { isSystemContentType, ObjectTypes } from '@crombolo/core'
15
15
  import {
16
16
  ComponentRepository,
@@ -18,6 +18,8 @@ import {
18
18
  currentSchemaState,
19
19
  type Db,
20
20
  DocumentRepository,
21
+ type MediaAccessEntry,
22
+ MediaAccessRepository,
21
23
  type NodeRow,
22
24
  PublicAccessRepository,
23
25
  RedirectRepository,
@@ -27,6 +29,7 @@ import {
27
29
  type BundleBlob,
28
30
  type BundleDependency,
29
31
  type BundleKind,
32
+ type BundleMediaAccess,
30
33
  type BundleNode,
31
34
  type BundleSnapshot,
32
35
  type BundleValue,
@@ -114,6 +117,32 @@ function toBundleValue(value: DocumentValue, references: readonly string[]): Bun
114
117
  }
115
118
  }
116
119
 
120
+ /** What a media node carries of its permissions; undefined when it sets none. Pure. */
121
+ export function mediaAccessOf(
122
+ rule: MediaAccessEntry | undefined,
123
+ item: MediaItemAccess | undefined,
124
+ ): BundleMediaAccess | undefined {
125
+ const carried: BundleMediaAccess = {
126
+ ...(rule
127
+ ? {
128
+ rule: {
129
+ publicRead: rule.publicRead,
130
+ groups: rule.groups.map((g) => ({ name: g.name, read: g.read, write: g.write })),
131
+ ...(rule.members?.length ? { members: [...rule.members] } : {}),
132
+ newRead: rule.newRead,
133
+ newWrite: rule.newWrite,
134
+ ...(rule.memberTypes.length > 0 ? { memberTypes: [...rule.memberTypes] } : {}),
135
+ ...(rule.memberMaxBytes ? { memberMaxBytes: rule.memberMaxBytes } : {}),
136
+ },
137
+ }
138
+ : {}),
139
+ ...(item && item.readPolicy !== 'inherit' ? { readPolicy: item.readPolicy } : {}),
140
+ ...(item && item.writePolicy !== 'inherit' ? { writePolicy: item.writePolicy } : {}),
141
+ ...(item?.creatorMemberKey ? { creator: item.creatorMemberKey } : {}),
142
+ }
143
+ return Object.keys(carried).length > 0 ? carried : undefined
144
+ }
145
+
117
146
  function toBundleNode(
118
147
  node: NodeRow,
119
148
  kind: BundleKind,
@@ -251,7 +280,16 @@ export async function exportBundle(db: Db, options: ExportOptions): Promise<Expo
251
280
  // routes it used to answer on.
252
281
  const access = new PublicAccessRepository(db)
253
282
  const redirects = new RedirectRepository(db)
283
+ const mediaAccess = new MediaAccessRepository(db)
254
284
  for (const node of bundleNodes) {
285
+ if (node.kind === 'media') {
286
+ const carried = mediaAccessOf(
287
+ await mediaAccess.byNodeKey(node.key),
288
+ await mediaAccess.itemAccess(node.key),
289
+ )
290
+ if (carried) node.mediaAccess = carried
291
+ continue
292
+ }
255
293
  if (node.kind !== 'document') continue
256
294
  const entry = await access.byNodeKey(node.key)
257
295
  if (entry)
package/src/import.ts CHANGED
@@ -47,6 +47,7 @@ import {
47
47
  DocumentRepository,
48
48
  insideTransaction,
49
49
  Locks,
50
+ MediaAccessRepository,
50
51
  PublicAccessRepository,
51
52
  PublishBlockedError,
52
53
  RedirectRepository,
@@ -424,6 +425,7 @@ async function applyBundle(tx: Db, set: ContentSet, options: ImportOptions): Pro
424
425
  // The rules a node carries, once every node they name exists.
425
426
  const rules = { access: 0, schedules: 0, redirects: 0 }
426
427
  const access = new PublicAccessRepository(tx)
428
+ const mediaAccess = new MediaAccessRepository(tx)
427
429
  const redirects = new RedirectRepository(tx)
428
430
  const nodesHere = repoFor('document').nodes
429
431
  for (const node of ordered) {
@@ -437,6 +439,19 @@ async function applyBundle(tx: Db, set: ContentSet, options: ImportOptions): Pro
437
439
  })
438
440
  if (saved) rules.access += 1
439
441
  }
442
+ // A media node's permissions as they were there; its creator is kept as a
443
+ // member key, and is that member wherever one has it.
444
+ if (node.kind === 'media' && node.mediaAccess) {
445
+ const carried = node.mediaAccess
446
+ if (carried.rule) {
447
+ if (await mediaAccess.save({ nodeKey: node.key, ...carried.rule })) rules.access += 1
448
+ } else await mediaAccess.remove(node.key)
449
+ await mediaAccess.setItemAccess(node.key, {
450
+ readPolicy: carried.readPolicy ?? 'inherit',
451
+ writePolicy: carried.writePolicy ?? 'inherit',
452
+ })
453
+ await mediaAccess.setCreator(node.key, carried.creator ?? null)
454
+ }
440
455
  if (node.schedule && node.schedule.length > 0 && node.kind === 'document') {
441
456
  const byCulture = new Map<
442
457
  string | null,
package/src/load.ts CHANGED
@@ -8,13 +8,15 @@
8
8
  */
9
9
 
10
10
  import { existsSync, readdirSync, readFileSync } from 'node:fs'
11
- import { join } from 'node:path'
11
+ import { join, relative, sep } from 'node:path'
12
12
  import {
13
13
  BUNDLE_FORMAT_VERSION,
14
14
  BUNDLE_SECTIONS,
15
15
  type BundleAccess,
16
+ type BundleBlob,
16
17
  type BundleKind,
17
18
  type BundleManifest,
19
+ type BundleMediaAccess,
18
20
  type BundleNode,
19
21
  type BundleProblem,
20
22
  type BundleRedirect,
@@ -28,9 +30,12 @@ import {
28
30
  import { type BundlePeople, openPeople, type PeopleBlock, parsePeopleBlock } from './people.ts'
29
31
  import { openBytes, parseSealParameters, unlock } from './seal.ts'
30
32
  import {
31
- blobPath,
32
33
  bundleIntegrity,
33
34
  MANIFEST_FILE,
35
+ MEDIA_DIR,
36
+ MEDIA_MANIFEST,
37
+ mediaPath,
38
+ mediaUri,
34
39
  nodePath,
35
40
  type SealedValues,
36
41
  sectionOf,
@@ -159,6 +164,7 @@ export function parseNode(
159
164
  if (variants.length === 0) problems.push({ file, message: 'no variants: a node needs a name' })
160
165
 
161
166
  const access = parseAccess(raw.access)
167
+ const mediaAccess = kind === 'media' ? parseMediaAccess(raw.mediaAccess) : undefined
162
168
  const schedule = Array.isArray(raw.schedule)
163
169
  ? raw.schedule.flatMap((e): BundleSchedule[] =>
164
170
  isRecord(e) &&
@@ -193,6 +199,7 @@ export function parseNode(
193
199
  variants,
194
200
  values,
195
201
  ...(access ? { access } : {}),
202
+ ...(mediaAccess ? { mediaAccess } : {}),
196
203
  ...(schedule.length > 0 ? { schedule } : {}),
197
204
  ...(redirects.length > 0 ? { redirects } : {}),
198
205
  }
@@ -214,6 +221,61 @@ function parseAccess(raw: unknown): BundleAccess | undefined {
214
221
  }
215
222
  }
216
223
 
224
+ const ITEM_POLICIES = ['public', 'members', 'groups', 'creator', 'none'] as const
225
+ const NEW_READ = ['public', 'none', 'members', 'groups', 'creator'] as const
226
+ const NEW_WRITE = ['groups', 'creator', 'none'] as const
227
+ const oneOf = <T extends string>(values: readonly T[], v: unknown): T | undefined =>
228
+ values.includes(v as T) ? (v as T) : undefined
229
+
230
+ function parseMediaAccess(raw: unknown): BundleMediaAccess | undefined {
231
+ if (!isRecord(raw)) return undefined
232
+ const rule = isRecord(raw.rule)
233
+ ? {
234
+ publicRead: raw.rule.publicRead === true,
235
+ groups: Array.isArray(raw.rule.groups)
236
+ ? raw.rule.groups.flatMap((g) =>
237
+ isRecord(g) && typeof g.name === 'string' && g.name
238
+ ? [{ name: g.name, read: g.read === true, write: g.write === true }]
239
+ : [],
240
+ )
241
+ : [],
242
+ newRead: oneOf(NEW_READ, raw.rule.newRead) ?? null,
243
+ ...(Array.isArray(raw.rule.members)
244
+ ? {
245
+ members: raw.rule.members.flatMap((m) =>
246
+ isRecord(m) &&
247
+ typeof m.key === 'string' &&
248
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(m.key)
249
+ ? [{ key: m.key.toLowerCase(), read: m.read === true, write: m.write === true }]
250
+ : [],
251
+ ),
252
+ }
253
+ : {}),
254
+ newWrite: oneOf(NEW_WRITE, raw.rule.newWrite) ?? null,
255
+ ...(Array.isArray(raw.rule.memberTypes)
256
+ ? {
257
+ memberTypes: raw.rule.memberTypes.filter(
258
+ (t): t is string => typeof t === 'string' && t !== '',
259
+ ),
260
+ }
261
+ : {}),
262
+ ...(typeof raw.rule.memberMaxBytes === 'number' && raw.rule.memberMaxBytes > 0
263
+ ? { memberMaxBytes: raw.rule.memberMaxBytes }
264
+ : {}),
265
+ }
266
+ : undefined
267
+ const readPolicy = oneOf(ITEM_POLICIES, raw.readPolicy)
268
+ const writePolicy = oneOf(ITEM_POLICIES, raw.writePolicy)
269
+ const creator = str(raw.creator)
270
+ const parsed: BundleMediaAccess = {
271
+ ...(rule ? { rule } : {}),
272
+ ...(readPolicy ? { readPolicy } : {}),
273
+ ...(writePolicy ? { writePolicy } : {}),
274
+ ...(creator ? { creator } : {}),
275
+ }
276
+ return Object.keys(parsed).length > 0 ? parsed : undefined
277
+ }
278
+
217
279
  function parseManifest(text: string, problems: BundleProblem[]): BundleManifest | undefined {
218
280
  let raw: unknown
219
281
  try {
@@ -298,21 +360,9 @@ function parseManifest(text: string, problems: BundleProblem[]): BundleManifest
298
360
  languages: keys(schema.languages),
299
361
  },
300
362
  },
301
- blobs: Array.isArray(raw.blobs)
302
- ? raw.blobs.flatMap((b) =>
303
- isRecord(b) && typeof b.key === 'string'
304
- ? [
305
- {
306
- key: b.key,
307
- node: str(b.node) ?? '',
308
- etag: nullableStr(b.etag) ?? null,
309
- size: typeof b.size === 'number' ? b.size : null,
310
- included: b.included === true,
311
- },
312
- ]
313
- : [],
314
- )
315
- : [],
363
+ // Filled from `media.json` by the loader, which the hash covers (story 195).
364
+ blobs: [],
365
+ ...(raw.mediaManifest === MEDIA_MANIFEST ? { mediaManifest: MEDIA_MANIFEST } : {}),
316
366
  ...(isRecord(raw.carries) ? { carries: parseCarries(raw.carries) } : {}),
317
367
  ...(raw.people !== undefined && parsePeopleBlock(raw.people)
318
368
  ? { people: parsePeopleBlock(raw.people) as PeopleBlock }
@@ -355,7 +405,70 @@ function parseCarries(raw: Record<string, unknown>): Partial<Record<BundleSectio
355
405
 
356
406
  /** Why a bundle in the layout before format 4 is refused, and what to do about it. */
357
407
  export const OLD_LAYOUT =
358
- 'this bundle was written before crombolo 0.33.1, in a layout no longer read; rebuild it with the command that made it (bundle build, content export, export, or a created package download)'
408
+ 'this bundle was written by an older crombolo, in a layout no longer read; rebuild it with the command that made it (bundle build, content export, export, or a created package download)'
409
+
410
+ /**
411
+ * `media.json`, read and checked: each entry's URI must be this bundle's own
412
+ * `bundle://<id>/media/<key>`, because nothing outside the package is fetched
413
+ * yet (story 195). Undefined when there is none; a problem when `bundle.json`
414
+ * says there is one and it is missing or malformed.
415
+ */
416
+ function readMediaManifest(
417
+ dir: string,
418
+ manifest: BundleManifest,
419
+ problems: BundleProblem[],
420
+ ): { blobs: BundleBlob[]; text: string } | undefined {
421
+ const file = join(dir, MEDIA_MANIFEST)
422
+ if (!manifest.mediaManifest) {
423
+ if (existsSync(file))
424
+ problems.push({ file: MEDIA_MANIFEST, message: 'bundle.json does not declare this file' })
425
+ return undefined
426
+ }
427
+ if (!existsSync(file)) {
428
+ problems.push({ file: MEDIA_MANIFEST, message: 'bundle.json declares it, and it is missing' })
429
+ return undefined
430
+ }
431
+ const text = readFileSync(file, 'utf8')
432
+ let raw: unknown
433
+ try {
434
+ raw = JSON.parse(text)
435
+ } catch {
436
+ problems.push({ file: MEDIA_MANIFEST, message: 'not valid JSON' })
437
+ return undefined
438
+ }
439
+ const files = isRecord(raw) && Array.isArray(raw.files) ? raw.files : undefined
440
+ if (!files) {
441
+ problems.push({ file: MEDIA_MANIFEST, message: 'has no list of files' })
442
+ return undefined
443
+ }
444
+ const blobs: BundleBlob[] = []
445
+ for (const entry of files) {
446
+ if (!isRecord(entry) || typeof entry.key !== 'string' || !isSafeKey(entry.key)) {
447
+ problems.push({ file: MEDIA_MANIFEST, message: 'lists a file with no usable key' })
448
+ continue
449
+ }
450
+ const uri = str(entry.uri)
451
+ if (uri !== undefined && uri !== mediaUri(manifest.id, entry.key)) {
452
+ problems.push({
453
+ file: MEDIA_MANIFEST,
454
+ message: `${entry.key} points at ${uri}, which is not this bundle's own copy; only files inside the bundle are read`,
455
+ })
456
+ continue
457
+ }
458
+ blobs.push({
459
+ key: entry.key,
460
+ node: str(entry.node) ?? '',
461
+ etag: nullableStr(entry.etag) ?? null,
462
+ size: typeof entry.size === 'number' ? entry.size : null,
463
+ included: uri !== undefined,
464
+ })
465
+ }
466
+ return { blobs, text }
467
+ }
468
+
469
+ /** A media key that stays inside `media/`. */
470
+ const isSafeKey = (key: string): boolean =>
471
+ key !== '' && !key.startsWith('/') && !key.split('/').some((part) => part === '' || part === '..')
359
472
 
360
473
  /** Reads a bundle directory. `set` is undefined when it cannot be trusted at all. */
361
474
  export function loadBundle(dir: string): LoadedBundle {
@@ -383,11 +496,19 @@ export function loadBundle(dir: string): LoadedBundle {
383
496
  }),
384
497
  )
385
498
 
499
+ // The media files are listed in `media.json`, read here and hashed with the
500
+ // rest, so the list is as much a checked claim as the files it names.
501
+ const listed = readMediaManifest(dir, manifest, problems)
502
+ if (listed) {
503
+ manifest.blobs = listed.blobs
504
+ read.push({ path: MEDIA_MANIFEST, text: listed.text })
505
+ }
506
+
386
507
  // A blob the manifest says it carries has to be here, and has to be the file
387
508
  // the hash was taken over: `included` is a claim, and this is what checks it.
388
509
  for (const blob of manifest.blobs) {
389
510
  if (!blob.included) continue
390
- const path = blobPath(blob.key)
511
+ const path = mediaPath(blob.key)
391
512
  const file = join(dir, path)
392
513
  if (!existsSync(file)) {
393
514
  problems.push({
@@ -400,6 +521,19 @@ export function loadBundle(dir: string): LoadedBundle {
400
521
  read.push({ path, bytes: new Uint8Array(readFileSync(file)) })
401
522
  }
402
523
 
524
+ // A file under `media/` that nothing lists would travel unhashed and unread;
525
+ // refused, so adding a file is caught as surely as editing one.
526
+ const mediaDir = join(dir, MEDIA_DIR)
527
+ if (existsSync(mediaDir)) {
528
+ const carried = new Set(manifest.blobs.filter((b) => b.included).map((b) => mediaPath(b.key)))
529
+ for (const entry of readdirSync(mediaDir, { recursive: true, withFileTypes: true })) {
530
+ if (!entry.isFile()) continue
531
+ const path = relative(dir, join(entry.parentPath, entry.name)).split(sep).join('/')
532
+ if (!carried.has(path))
533
+ problems.push({ file: path, message: 'this file is not listed in media.json' })
534
+ }
535
+ }
536
+
403
537
  // Every file the manifest says it carries has to be here, and has to be the
404
538
  // file the hash was taken over — the same rule as a blob's `included`.
405
539
  for (const [, paths] of Object.entries(manifest.carries ?? {})) {
@@ -555,6 +689,6 @@ export function openBundle(
555
689
  return {
556
690
  set: { ...rest, nodes, ...(people ? { people } : {}) },
557
691
  people,
558
- openBlob: (blob, bytes) => (sealedBlobs ? openBytes(key, blobPath(blob), bytes) : bytes),
692
+ openBlob: (blob, bytes) => (sealedBlobs ? openBytes(key, mediaPath(blob), bytes) : bytes),
559
693
  }
560
694
  }
package/src/model.ts CHANGED
@@ -16,14 +16,17 @@ import type { SealParameters } from './seal.ts'
16
16
  * a bundle. Every bundle is written at this version.
17
17
  *
18
18
  * 4 (0.33.1): `bundle.json` at the package root, with what it carries beside
19
- * it, and a site's code as a section (stories 192, 193). Versions 1–3 kept the
20
- * payload in `content/`, and are refused rather than read (no older layout is
21
- * kept up), with a message saying to rebuild them.
19
+ * it, and a site's code as a section (stories 192, 193).
20
+ * 5: media listed in `media.json` at the root, each carried file at
21
+ * `media/<key>` with a `bundle://` URI (story 195).
22
+ *
23
+ * An older version is refused rather than read (no older layout is kept up),
24
+ * with a message saying to rebuild it.
22
25
  */
23
- export const BUNDLE_FORMAT_VERSION = 4
26
+ export const BUNDLE_FORMAT_VERSION = 5
24
27
 
25
- /** The oldest version this reader reads: the first with the payload at the package root. */
26
- export const OLDEST_BUNDLE_FORMAT_VERSION = 4
28
+ /** The oldest version this reader reads: the first with media listed in `media.json`. */
29
+ export const OLDEST_BUNDLE_FORMAT_VERSION = 5
27
30
 
28
31
  /**
29
32
  * The sections a bundle can carry beyond its content, and the directory each
@@ -99,6 +102,26 @@ export interface BundleAccess {
99
102
  memberUserNames?: string[]
100
103
  }
101
104
 
105
+ /**
106
+ * Who may read and change a media folder or item (story 196): the rule set on
107
+ * it, its own policies, and the member who created it, by key.
108
+ */
109
+ export interface BundleMediaAccess {
110
+ rule?: {
111
+ publicRead: boolean
112
+ groups: Array<{ name: string; read: boolean; write: boolean }>
113
+ members?: Array<{ key: string; read: boolean; write: boolean }>
114
+ newRead: 'public' | 'members' | 'groups' | 'creator' | 'none' | null
115
+ newWrite: 'groups' | 'creator' | 'none' | null
116
+ /** File types members may upload below (story 198); absent is none. */
117
+ memberTypes?: string[]
118
+ memberMaxBytes?: number
119
+ }
120
+ readPolicy?: 'public' | 'members' | 'groups' | 'creator' | 'none'
121
+ writePolicy?: 'public' | 'members' | 'groups' | 'creator' | 'none'
122
+ creator?: string
123
+ }
124
+
102
125
  /** A publish or unpublish waiting for its time. */
103
126
  export interface BundleSchedule {
104
127
  culture: string | null
@@ -127,6 +150,7 @@ export interface BundleNode {
127
150
  variants: BundleVariant[]
128
151
  values: BundleValue[]
129
152
  access?: BundleAccess
153
+ mediaAccess?: BundleMediaAccess
130
154
  schedule?: BundleSchedule[]
131
155
  redirects?: BundleRedirect[]
132
156
  }
@@ -209,6 +233,11 @@ export interface BundleManifest {
209
233
  counts: Partial<Record<BundleKind, number>>
210
234
  dependencies: BundleDependencies
211
235
  blobs: BundleBlob[]
236
+ /**
237
+ * `media.json`, when the bundle names any media file: the list of them, at
238
+ * the package root and inside the hash (story 195). `blobs` is read from it.
239
+ */
240
+ mediaManifest?: string
212
241
  /**
213
242
  * The files this bundle carries beyond its content and media, by section, in
214
243
  * path order — the structure and the views that make a bundle installable
package/src/write.ts CHANGED
@@ -14,6 +14,7 @@
14
14
  import {
15
15
  BUNDLE_FORMAT_VERSION,
16
16
  BUNDLE_SECTIONS,
17
+ type BundleBlob,
17
18
  type BundleContentMode,
18
19
  type BundleManifest,
19
20
  type BundleNode,
@@ -92,6 +93,23 @@ export function writeNode(node: BundleNode, sealed = false): string {
92
93
  },
93
94
  }
94
95
  : {}),
96
+ ...(node.mediaAccess
97
+ ? {
98
+ mediaAccess: {
99
+ ...node.mediaAccess,
100
+ ...(node.mediaAccess.rule
101
+ ? {
102
+ rule: {
103
+ ...node.mediaAccess.rule,
104
+ groups: [...node.mediaAccess.rule.groups].sort((a, b) =>
105
+ a.name.localeCompare(b.name),
106
+ ),
107
+ },
108
+ }
109
+ : {}),
110
+ },
111
+ }
112
+ : {}),
95
113
  ...(node.schedule && node.schedule.length > 0
96
114
  ? {
97
115
  schedule: [...node.schedule]
@@ -176,15 +194,9 @@ export function writeManifest(manifest: BundleManifest): string {
176
194
  languages: [...d.schema.languages].sort(),
177
195
  },
178
196
  },
179
- blobs: [...manifest.blobs]
180
- .sort((a, b) => a.key.localeCompare(b.key))
181
- .map((b) => ({
182
- key: b.key,
183
- node: b.node,
184
- etag: b.etag,
185
- size: b.size,
186
- included: b.included,
187
- })),
197
+ // The files themselves are listed in `media.json`, which the hash covers;
198
+ // this file, which holds the hash, only says that there is one (story 195).
199
+ ...(manifest.blobs.length > 0 ? { mediaManifest: MEDIA_MANIFEST } : {}),
188
200
  // Absent on a content-only bundle, so version 1 output is unchanged.
189
201
  ...(manifest.carries && Object.keys(manifest.carries).length > 0
190
202
  ? { carries: sortedCarries(manifest.carries) }
@@ -224,7 +236,41 @@ export function sectionOf(path: string): BundleSection | undefined {
224
236
  }
225
237
 
226
238
  /** Where a media file's bytes sit when the bundle carries them. */
227
- export const blobPath = (key: string): string => `blobs/${key}`
239
+ export const mediaPath = (key: string): string => `${MEDIA_DIR}/${key}`
240
+
241
+ /** The directory a bundle's media files sit in. */
242
+ export const MEDIA_DIR = 'media'
243
+
244
+ /** The media manifest, at the package root beside `bundle.json` (story 195). */
245
+ export const MEDIA_MANIFEST = 'media.json'
246
+
247
+ /**
248
+ * A carried media file's address: `bundle://<id>/media/<key>`, absolute and
249
+ * naming the bundle, so it means the same wherever the package is copied.
250
+ */
251
+ export function mediaUri(bundleId: string, key: string): string {
252
+ const path = key.split('/').map(encodeURIComponent).join('/')
253
+ return `bundle://${encodeURIComponent(bundleId)}/${MEDIA_DIR}/${path}`
254
+ }
255
+
256
+ /**
257
+ * `media.json`: every media file the content names, with a URI for each the
258
+ * bundle carries. A file listed without one is left out or, in a remote's
259
+ * referenced file, fetched from that remote by key.
260
+ */
261
+ export function writeMediaManifest(bundleId: string, blobs: readonly BundleBlob[]): string {
262
+ return json({
263
+ files: [...blobs]
264
+ .sort((a, b) => a.key.localeCompare(b.key))
265
+ .map((b) => ({
266
+ key: b.key,
267
+ node: b.node,
268
+ etag: b.etag,
269
+ size: b.size,
270
+ ...(b.included ? { uri: mediaUri(bundleId, b.key) } : {}),
271
+ })),
272
+ })
273
+ }
228
274
 
229
275
  export const MANIFEST_FILE = 'bundle.json'
230
276
 
@@ -296,7 +342,7 @@ export function writeBundle(
296
342
  const sizes = new Map([...blobs].map(([key, bytes]) => [key, bytes.length]))
297
343
  const planned = planBundle(set, sizes, sections, options)
298
344
  const carried: BundleFile[] = planned.blobs.map((key) => {
299
- const path = blobPath(key)
345
+ const path = mediaPath(key)
300
346
  const bytes = blobs.get(key) as Uint8Array
301
347
  return {
302
348
  path,
@@ -313,7 +359,7 @@ export function writeBundle(
313
359
  /**
314
360
  * A bundle whose media files the caller streams (story 104): the manifest and
315
361
  * every other file, from each carried file's size alone. The caller writes
316
- * `blobs` at `blobPath` — sealed with `sealBytes` under the seal when `sealing`
362
+ * `blobs` at `mediaPath` — sealed with `sealBytes` under the seal when `sealing`
317
363
  * — computes `bundleIntegrity` over those and `files` in path order, and writes
318
364
  * the manifest with it.
319
365
  */
@@ -379,9 +425,13 @@ function planBundle(
379
425
  content: content === 'open' ? undefined : content,
380
426
  integrity: '',
381
427
  }
428
+ const media: BundleFile[] =
429
+ manifest.blobs.length > 0
430
+ ? [{ path: MEDIA_MANIFEST, text: writeMediaManifest(manifest.id, manifest.blobs) }]
431
+ : []
382
432
  return {
383
433
  manifest,
384
- files: [...nodes, ...sealedFiles, ...extra, ...(people?.files ?? [])],
434
+ files: [...nodes, ...sealedFiles, ...extra, ...(people?.files ?? []), ...media],
385
435
  blobs: [...carriedSizes.keys()].sort((a, b) => a.localeCompare(b)),
386
436
  sealing,
387
437
  }