Design: Database: BID-Entries meta

Database		BID-Entries (BID is randomly generated ulid for a bundle)
Purpose		Hold names, sizes and content types of files in a bundle.
Cardinality		one BID-Entries database per bundle in the engagement one item whose associated file contains the bundle's encoded entry metadata
Source Code
	Items	src/ts/dbitems/BID-Entries.ts
Zod Models
	item	BIDEntriesItem
	item.item	BIDEntriesRecord
Attributes
	itemId	number of bundle in the Bundles database
	item:	BIDEntriesRecord
	kind	'bidentries'
	bnum	number of bundle in the Bundles database (same as itemId)
	root	root from bundle settings
	start	start from bundle settings
	dirindex	dirindex from bundle settings

Description

Members may view and examine the details and the summary metadata of bundles shared with them at any time. Members may inspect bundles before agreeing to any conditions or engaging with file contents. A member may choose not to engage with a bundle that appears suspicious, inappropriate, or too large.

To support this the summary metadata is represented as a collection of Entries objects, each of which holds metadata about the entries in a single directory, similar to a directory listing.

While it would be convenient to map each Entries object to a corresponding Userbase item, the size limit of a Userbase item is approximately 5120 2-byte characters (10 KiB). This is too small so Javascript Entries objects are split into pages and encoded into a buffer stored in the "file" of a single BIDEntriesItem in the BID-Entries database.

(see userbase-js/types/index.d.ts)

  export interface Item {          item                          file
    itemId: string               ╭────────────────────────┐     ┌────────┬──────┬─────┬──────┐
    item: any ──────────────────▶│ kind: 'bidentries'     │╶╶╶╶ │ header │ page │ ... │ page │
    createdBy: Attribution       │ bnum: 1                │     └────────┴──────┴─────┴──────┘
    updatedBy?: Attribution      │ root: '/'              │
    fileId?: string              │ start: '/'             │
    fileName?: string            │ dirindex: 'index.html' │
    fileSize?: number            ╰────────────────────────┘
    fileUploadedBy?: Attribution
    writeAccess?: AccessControl
  }

The database name uses the randomly generated BID (bundle ID) from the corresponding record in the Bundles database as a prefix.

Ownership and Access

The BID-Entries database is owned by the host.

It is initially not shared with any members and readable only by the host.

When the host shares bundle with a member the corresponding BID-Entries Userbase database is shared with the member's GUEST user.

Zod models

The following Zod models show how the Userbase items are represented in memory.

Note that in addition to the values specified by the Userbase Item interface the kind and database attributes are added during deserialization.

export type  BIDEntriesItem = z.infer<typeof BIDEntriesItem>;
export const BIDEntriesItem = z.object({
  kind:                 z.literal('bidentriesitem'),
  fileId:               z.string().optional(),
  itemId:               z.string(),
  item:                 BIDEntriesRecord,
  updatedBy:            z.custom<Attribution>(),
  database:             z.custom<Database>()
}).strip();

/*
 * BIDEntriesRecord     metadata stored in userbase record.
 *                      data read/written with getFile/uploadFile.
 */
export type  BIDEntriesRecord = z.infer<typeof BIDEntriesRecord>;
export const BIDEntriesRecord = z.object({
  kind:                 z.literal('bidentries'),
  bnum:                 z.number(),
  root:                 z.string(),
  start:                z.string(),
  dirindex:             z.string()
}).strip();