@crombolo/transfer 0.33.1 → 0.35.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/README.md ADDED
@@ -0,0 +1,14 @@
1
+ # @crombolo/transfer
2
+
3
+ **Internal to crombolo.** This package is published because
4
+ [`@crombolo/crombolo`](https://www.npmjs.com/package/@crombolo/crombolo)
5
+ depends on it, and its exports can change in any release, a patch included.
6
+
7
+ Import from `@crombolo/crombolo` instead:
8
+
9
+ - `@crombolo/crombolo` for a site: its config, its boot and its views.
10
+ - `@crombolo/crombolo/bundle` for a server bundle's author.
11
+ - `@crombolo/crombolo/host` for whoever runs sites.
12
+
13
+ Those three entry points carry the compatibility promise in
14
+ [`docs/api.md`](https://github.com/kineco-au/crombolo-cms/blob/main/docs/api.md).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@crombolo/transfer",
3
- "version": "0.33.1",
4
- "description": "Content transfer for crombolo: bundles of content moved between environments.",
3
+ "version": "0.35.2",
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",
7
7
  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
@@ -28,7 +28,7 @@
28
28
  "access": "public"
29
29
  },
30
30
  "dependencies": {
31
- "@crombolo/core": "0.33.1",
32
- "@crombolo/data": "0.33.1"
31
+ "@crombolo/core": "0.35.2",
32
+ "@crombolo/data": "0.35.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,31 @@ 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
+ newRead: rule.newRead,
132
+ newWrite: rule.newWrite,
133
+ ...(rule.memberTypes.length > 0 ? { memberTypes: [...rule.memberTypes] } : {}),
134
+ ...(rule.memberMaxBytes ? { memberMaxBytes: rule.memberMaxBytes } : {}),
135
+ },
136
+ }
137
+ : {}),
138
+ ...(item && item.readPolicy !== 'inherit' ? { readPolicy: item.readPolicy } : {}),
139
+ ...(item && item.writePolicy !== 'inherit' ? { writePolicy: item.writePolicy } : {}),
140
+ ...(item?.creatorMemberKey ? { creator: item.creatorMemberKey } : {}),
141
+ }
142
+ return Object.keys(carried).length > 0 ? carried : undefined
143
+ }
144
+
117
145
  function toBundleNode(
118
146
  node: NodeRow,
119
147
  kind: BundleKind,
@@ -251,7 +279,16 @@ export async function exportBundle(db: Db, options: ExportOptions): Promise<Expo
251
279
  // routes it used to answer on.
252
280
  const access = new PublicAccessRepository(db)
253
281
  const redirects = new RedirectRepository(db)
282
+ const mediaAccess = new MediaAccessRepository(db)
254
283
  for (const node of bundleNodes) {
284
+ if (node.kind === 'media') {
285
+ const carried = mediaAccessOf(
286
+ await mediaAccess.byNodeKey(node.key),
287
+ await mediaAccess.itemAccess(node.key),
288
+ )
289
+ if (carried) node.mediaAccess = carried
290
+ continue
291
+ }
255
292
  if (node.kind !== 'document') continue
256
293
  const entry = await access.byNodeKey(node.key)
257
294
  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,50 @@ function parseAccess(raw: unknown): BundleAccess | undefined {
214
221
  }
215
222
  }
216
223
 
224
+ const ITEM_POLICIES = ['public', 'groups', 'creator', 'none'] as const
225
+ const NEW_READ = ['public', '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
+ newWrite: oneOf(NEW_WRITE, raw.rule.newWrite) ?? null,
244
+ ...(Array.isArray(raw.rule.memberTypes)
245
+ ? {
246
+ memberTypes: raw.rule.memberTypes.filter(
247
+ (t): t is string => typeof t === 'string' && t !== '',
248
+ ),
249
+ }
250
+ : {}),
251
+ ...(typeof raw.rule.memberMaxBytes === 'number' && raw.rule.memberMaxBytes > 0
252
+ ? { memberMaxBytes: raw.rule.memberMaxBytes }
253
+ : {}),
254
+ }
255
+ : undefined
256
+ const readPolicy = oneOf(ITEM_POLICIES, raw.readPolicy)
257
+ const writePolicy = oneOf(ITEM_POLICIES, raw.writePolicy)
258
+ const creator = str(raw.creator)
259
+ const parsed: BundleMediaAccess = {
260
+ ...(rule ? { rule } : {}),
261
+ ...(readPolicy ? { readPolicy } : {}),
262
+ ...(writePolicy ? { writePolicy } : {}),
263
+ ...(creator ? { creator } : {}),
264
+ }
265
+ return Object.keys(parsed).length > 0 ? parsed : undefined
266
+ }
267
+
217
268
  function parseManifest(text: string, problems: BundleProblem[]): BundleManifest | undefined {
218
269
  let raw: unknown
219
270
  try {
@@ -298,21 +349,9 @@ function parseManifest(text: string, problems: BundleProblem[]): BundleManifest
298
349
  languages: keys(schema.languages),
299
350
  },
300
351
  },
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
- : [],
352
+ // Filled from `media.json` by the loader, which the hash covers (story 195).
353
+ blobs: [],
354
+ ...(raw.mediaManifest === MEDIA_MANIFEST ? { mediaManifest: MEDIA_MANIFEST } : {}),
316
355
  ...(isRecord(raw.carries) ? { carries: parseCarries(raw.carries) } : {}),
317
356
  ...(raw.people !== undefined && parsePeopleBlock(raw.people)
318
357
  ? { people: parsePeopleBlock(raw.people) as PeopleBlock }
@@ -355,7 +394,70 @@ function parseCarries(raw: Record<string, unknown>): Partial<Record<BundleSectio
355
394
 
356
395
  /** Why a bundle in the layout before format 4 is refused, and what to do about it. */
357
396
  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)'
397
+ '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)'
398
+
399
+ /**
400
+ * `media.json`, read and checked: each entry's URI must be this bundle's own
401
+ * `bundle://<id>/media/<key>`, because nothing outside the package is fetched
402
+ * yet (story 195). Undefined when there is none; a problem when `bundle.json`
403
+ * says there is one and it is missing or malformed.
404
+ */
405
+ function readMediaManifest(
406
+ dir: string,
407
+ manifest: BundleManifest,
408
+ problems: BundleProblem[],
409
+ ): { blobs: BundleBlob[]; text: string } | undefined {
410
+ const file = join(dir, MEDIA_MANIFEST)
411
+ if (!manifest.mediaManifest) {
412
+ if (existsSync(file))
413
+ problems.push({ file: MEDIA_MANIFEST, message: 'bundle.json does not declare this file' })
414
+ return undefined
415
+ }
416
+ if (!existsSync(file)) {
417
+ problems.push({ file: MEDIA_MANIFEST, message: 'bundle.json declares it, and it is missing' })
418
+ return undefined
419
+ }
420
+ const text = readFileSync(file, 'utf8')
421
+ let raw: unknown
422
+ try {
423
+ raw = JSON.parse(text)
424
+ } catch {
425
+ problems.push({ file: MEDIA_MANIFEST, message: 'not valid JSON' })
426
+ return undefined
427
+ }
428
+ const files = isRecord(raw) && Array.isArray(raw.files) ? raw.files : undefined
429
+ if (!files) {
430
+ problems.push({ file: MEDIA_MANIFEST, message: 'has no list of files' })
431
+ return undefined
432
+ }
433
+ const blobs: BundleBlob[] = []
434
+ for (const entry of files) {
435
+ if (!isRecord(entry) || typeof entry.key !== 'string' || !isSafeKey(entry.key)) {
436
+ problems.push({ file: MEDIA_MANIFEST, message: 'lists a file with no usable key' })
437
+ continue
438
+ }
439
+ const uri = str(entry.uri)
440
+ if (uri !== undefined && uri !== mediaUri(manifest.id, entry.key)) {
441
+ problems.push({
442
+ file: MEDIA_MANIFEST,
443
+ message: `${entry.key} points at ${uri}, which is not this bundle's own copy; only files inside the bundle are read`,
444
+ })
445
+ continue
446
+ }
447
+ blobs.push({
448
+ key: entry.key,
449
+ node: str(entry.node) ?? '',
450
+ etag: nullableStr(entry.etag) ?? null,
451
+ size: typeof entry.size === 'number' ? entry.size : null,
452
+ included: uri !== undefined,
453
+ })
454
+ }
455
+ return { blobs, text }
456
+ }
457
+
458
+ /** A media key that stays inside `media/`. */
459
+ const isSafeKey = (key: string): boolean =>
460
+ key !== '' && !key.startsWith('/') && !key.split('/').some((part) => part === '' || part === '..')
359
461
 
360
462
  /** Reads a bundle directory. `set` is undefined when it cannot be trusted at all. */
361
463
  export function loadBundle(dir: string): LoadedBundle {
@@ -383,11 +485,19 @@ export function loadBundle(dir: string): LoadedBundle {
383
485
  }),
384
486
  )
385
487
 
488
+ // The media files are listed in `media.json`, read here and hashed with the
489
+ // rest, so the list is as much a checked claim as the files it names.
490
+ const listed = readMediaManifest(dir, manifest, problems)
491
+ if (listed) {
492
+ manifest.blobs = listed.blobs
493
+ read.push({ path: MEDIA_MANIFEST, text: listed.text })
494
+ }
495
+
386
496
  // A blob the manifest says it carries has to be here, and has to be the file
387
497
  // the hash was taken over: `included` is a claim, and this is what checks it.
388
498
  for (const blob of manifest.blobs) {
389
499
  if (!blob.included) continue
390
- const path = blobPath(blob.key)
500
+ const path = mediaPath(blob.key)
391
501
  const file = join(dir, path)
392
502
  if (!existsSync(file)) {
393
503
  problems.push({
@@ -400,6 +510,19 @@ export function loadBundle(dir: string): LoadedBundle {
400
510
  read.push({ path, bytes: new Uint8Array(readFileSync(file)) })
401
511
  }
402
512
 
513
+ // A file under `media/` that nothing lists would travel unhashed and unread;
514
+ // refused, so adding a file is caught as surely as editing one.
515
+ const mediaDir = join(dir, MEDIA_DIR)
516
+ if (existsSync(mediaDir)) {
517
+ const carried = new Set(manifest.blobs.filter((b) => b.included).map((b) => mediaPath(b.key)))
518
+ for (const entry of readdirSync(mediaDir, { recursive: true, withFileTypes: true })) {
519
+ if (!entry.isFile()) continue
520
+ const path = relative(dir, join(entry.parentPath, entry.name)).split(sep).join('/')
521
+ if (!carried.has(path))
522
+ problems.push({ file: path, message: 'this file is not listed in media.json' })
523
+ }
524
+ }
525
+
403
526
  // Every file the manifest says it carries has to be here, and has to be the
404
527
  // file the hash was taken over — the same rule as a blob's `included`.
405
528
  for (const [, paths] of Object.entries(manifest.carries ?? {})) {
@@ -555,6 +678,6 @@ export function openBundle(
555
678
  return {
556
679
  set: { ...rest, nodes, ...(people ? { people } : {}) },
557
680
  people,
558
- openBlob: (blob, bytes) => (sealedBlobs ? openBytes(key, blobPath(blob), bytes) : bytes),
681
+ openBlob: (blob, bytes) => (sealedBlobs ? openBytes(key, mediaPath(blob), bytes) : bytes),
559
682
  }
560
683
  }
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,25 @@ 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
+ newRead: 'public' | 'groups' | 'creator' | null
114
+ newWrite: 'groups' | 'creator' | 'none' | null
115
+ /** File types members may upload below (story 198); absent is none. */
116
+ memberTypes?: string[]
117
+ memberMaxBytes?: number
118
+ }
119
+ readPolicy?: 'public' | 'groups' | 'creator' | 'none'
120
+ writePolicy?: 'public' | 'groups' | 'creator' | 'none'
121
+ creator?: string
122
+ }
123
+
102
124
  /** A publish or unpublish waiting for its time. */
103
125
  export interface BundleSchedule {
104
126
  culture: string | null
@@ -127,6 +149,7 @@ export interface BundleNode {
127
149
  variants: BundleVariant[]
128
150
  values: BundleValue[]
129
151
  access?: BundleAccess
152
+ mediaAccess?: BundleMediaAccess
130
153
  schedule?: BundleSchedule[]
131
154
  redirects?: BundleRedirect[]
132
155
  }
@@ -209,6 +232,11 @@ export interface BundleManifest {
209
232
  counts: Partial<Record<BundleKind, number>>
210
233
  dependencies: BundleDependencies
211
234
  blobs: BundleBlob[]
235
+ /**
236
+ * `media.json`, when the bundle names any media file: the list of them, at
237
+ * the package root and inside the hash (story 195). `blobs` is read from it.
238
+ */
239
+ mediaManifest?: string
212
240
  /**
213
241
  * The files this bundle carries beyond its content and media, by section, in
214
242
  * 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
  }