logo logo
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();