@hachej/boring-files 0.4.2 → 0.4.3

package/README.md

@@ -26,6 +26,17 @@ Receipts are scoped by workspace identity, principal, scope and initiator. Ident
 
 See [scaffold guide](../../docs/contracts/SCAFFOLD.md) and [resource design](../../docs/architecture/FILES-GIT-EXEC.md).
 
+### Large files (blob pointers) and media sniffing
+
+A large or binary file (up to 100 MB) can live in the host's blob store as an immutable blob while the workspace holds a small pointer file in its place, `<name>.blob.json` with media type `application/vnd.boring.blob+json`: `{ "boring:blob": 1, "id", "sha256", "size", "type", "name" }`. Where bytes live is the provider's business; the pointer is the provider's representation of a large immutable blob, written and read through the workspace's one provider like any file (no second place, no sync). The host serves the bytes at `GET <blobBase><encodeURIComponent(id)>` (default `/_files/`), same origin, checking access on every request and setting disposition, `nosniff` and a CSP. `@hachej/boring-files/blob` (pure, browser-safe) exports:
+
+- `parseBlobPointer(bytes | text)`: strict (input under `BLOB_POINTER_MAX_BYTES` = 4 KB, UTF-8 JSON, every field with its type, 64 lower-case hex digits, a non-negative safe-integer size, a media type, a name without path separators). It returns the pointer, `{ kind: 'unsupported-version', version }` for a higher `boring:blob` (show the file as JSON and say "newer format"), or `undefined`. Hosts validate with the same function.
+- `checkBlobBase(base)`: a same-origin path starting with one `/`; a scheme, a host, `//`, a backslash or whitespace is a `TypeError`. `blobItemOf(pointer, base)` and `resolveBlobPointer(bytes, base)` give `{ name, size, type, url }`, the only thing viewers see.
+- `withBlobPointers(provider, base)`: the revision provider as a listing reads it: each pointer file of a `list` or `search` page carries `blob` (`FileEntry.blob`), read once through the same provider. Reads still return the pointer's bytes.
+- `BLOB_POINTER_MEDIA_TYPE`, `BLOB_POINTER_SUFFIX`, `BLOB_POINTER_VERSION`, `DEFAULT_BLOB_BASE`, `isBlobPointerPath` and the `BlobPointer` / `BlobItem` types.
+
+`@hachej/boring-files/file-types` is the one table of what a file is. `sniffMediaType(head)` (pass up to `SNIFF_BYTES` = 8 KB) names PDF, PNG, JPEG, GIF, WebP, HEIC/HEIF (ISO-BMFF `ftyp` brands: `heic`, `heix`, `hevc`, … are HEIC; `mif1`/`msf1` are HEIC with a HEVC compatible brand, HEIF otherwise, unclaimed with an AVIF brand), and zip documents from the head alone: OpenDocument and EPUB by their stored `mimetype` entry, docx/xlsx/pptx by a `[Content_Types].xml` entry and then its main part type when it is stored, else the folder of a later entry (`word/`, `xl/`, `ppt/`). The head is never inflated (`[Content_Types].xml` is almost always deflated, and inflating is asynchronous in a browser), so a zip whose sizes are in a data descriptor is not claimed. Otherwise bytes that are valid UTF-8 with no NUL are `text/plain`, a weak answer that never overrides a name. `delimitedTextType(path, head)` says CSV or TSV from the extension when the bytes are text. `@hachej/boring-agent/file-types` reads this table and head size; it keeps only its own routing kinds.
+
 ## Node hosts
 
 `@hachej/boring-files/node-http` bridges `node:http` to the Fetch handlers of these packages: `webRequest(incoming, url, { signal, maxBytes })` reads the body first under a byte cap (never `Readable.toWeb` on a live request, whose cancellation kills the process) and `sendWebResponse(response, outgoing, { signal })` flushes the headers at once, keeps each `set-cookie`, waits for `drain` when the socket is full and cancels the web body when the client disconnects. The example servers use it; `npm run check` refuses hand-written response copies under `examples/`.

package/dist/blob.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Large files as blob pointers. A large or binary file (up to 100 MB) lives in the host's blob store as an immutable blob, and the
+ * workspace holds a small pointer file in its place (`<name>.blob.json`, media type `application/vnd.boring.blob+json`):
+ *
+ *   { "boring:blob": 1, "id": "<id>", "sha256": "<hex>", "size": <bytes>, "type": "<media type>", "name": "<file name>" }
+ *
+ * Where bytes live is the provider's business: the pointer is the provider's representation of a large immutable blob, written and
+ * read through the workspace's one provider like any other file. The host serves the bytes at `GET <blobBase><encodeURIComponent(id)>`
+ * (same origin, access checked on every request). This module reads pointers and names that URL; it never fetches. Pure: no Node, no DOM.
+ */
+import type { BlobItem, RevisionProvider, UnsupportedBlobPointer } from './revision-contracts.js';
+export type { BlobItem, UnsupportedBlobPointer } from './revision-contracts.js';
+/** The pointer file's media type. */
+export declare const BLOB_POINTER_MEDIA_TYPE = "application/vnd.boring.blob+json";
+/** The pointer format this module reads (`"boring:blob": 1`). A higher number is a newer format: `parseBlobPointer` says so. */
+export declare const BLOB_POINTER_VERSION = 1;
+/** A pointer file is small: anything this size or larger is not one. */
+export declare const BLOB_POINTER_MAX_BYTES = 4096;
+/** The ending of a pointer file's name in the workspace (`photos/cat.heic.blob.json`). */
+export declare const BLOB_POINTER_SUFFIX = ".blob.json";
+/** Where the host serves blob bytes by default: `GET /_files/<encodeURIComponent(id)>`. */
+export declare const DEFAULT_BLOB_BASE = "/_files/";
+/** A valid pointer, exactly the fields of the format. */
+export interface BlobPointer {
+    readonly 'boring:blob': 1;
+    readonly id: string;
+    /** Lower-case hex SHA-256 of the blob's bytes. */
+    readonly sha256: string;
+    /** The blob's size in bytes. */
+    readonly size: number;
+    /** The blob's media type. */
+    readonly type: string;
+    /** The file name shown for it (no path separators). */
+    readonly name: string;
+}
+/**
+ * Reads a pointer file's bytes (or text), strictly: input under `BLOB_POINTER_MAX_BYTES`, UTF-8 JSON, every field present with its
+ * type, `sha256` 64 lower-case hex digits, `size` a non-negative safe integer, `type` a media type, `name` a file name without path
+ * separators. Returns the pointer; `{ kind: 'unsupported-version' }` for a higher `boring:blob`; `undefined` for anything else.
+ */
+export declare function parseBlobPointer(input: Uint8Array | string): BlobPointer | UnsupportedBlobPointer | undefined;
+/** Whether a workspace path names a pointer file (`*.blob.json`). */
+export declare const isBlobPointerPath: (path: string) => boolean;
+/**
+ * The checked blob base: a same-origin path starting with one `/` (default `/_files/`). A URL with a scheme or host, a
+ * protocol-relative `//host`, a backslash, whitespace or a control character is refused with a `TypeError`.
+ */
+export declare function checkBlobBase(base?: string): string;
+/** The item a pointer stands for, with the URL of its bytes under a checked `base`. */
+export declare const blobItemOf: (pointer: BlobPointer, base?: string) => BlobItem;
+/** A pointer file's bytes as what to show: `{ kind: 'blob', item }`, an unsupported version, or `undefined` (not a pointer: show the file). */
+export declare function resolveBlobPointer(input: Uint8Array | string, base?: string): {
+    readonly kind: 'blob';
+    readonly item: BlobItem;
+} | UnsupportedBlobPointer | undefined;
+/**
+ * The provider as a listing reads it: each pointer file in a `list` or `search` page carries `blob` (the item it stands for, or its
+ * unsupported version), read once through the same provider. Every other call is the provider's own; reads still return the
+ * pointer's bytes, so a conditional write of the pointer file works as for any file. `base` is checked here, once.
+ */
+export declare function withBlobPointers(provider: RevisionProvider, base?: string): RevisionProvider;
+//# sourceMappingURL=blob.d.ts.map

package/dist/blob.js

@@ -0,0 +1,99 @@
+/** The pointer file's media type. */
+export const BLOB_POINTER_MEDIA_TYPE = 'application/vnd.boring.blob+json';
+/** The pointer format this module reads (`"boring:blob": 1`). A higher number is a newer format: `parseBlobPointer` says so. */
+export const BLOB_POINTER_VERSION = 1;
+/** A pointer file is small: anything this size or larger is not one. */
+export const BLOB_POINTER_MAX_BYTES = 4096;
+/** The ending of a pointer file's name in the workspace (`photos/cat.heic.blob.json`). */
+export const BLOB_POINTER_SUFFIX = '.blob.json';
+/** Where the host serves blob bytes by default: `GET /_files/<encodeURIComponent(id)>`. */
+export const DEFAULT_BLOB_BASE = '/_files/';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+const text = (value, max) => typeof value === 'string' && value.length > 0 && value.length <= max && !CONTROL.test(value);
+/**
+ * Reads a pointer file's bytes (or text), strictly: input under `BLOB_POINTER_MAX_BYTES`, UTF-8 JSON, every field present with its
+ * type, `sha256` 64 lower-case hex digits, `size` a non-negative safe integer, `type` a media type, `name` a file name without path
+ * separators. Returns the pointer; `{ kind: 'unsupported-version' }` for a higher `boring:blob`; `undefined` for anything else.
+ */
+export function parseBlobPointer(input) {
+    if (typeof input === 'string' ? input.length >= BLOB_POINTER_MAX_BYTES || new TextEncoder().encode(input).byteLength >= BLOB_POINTER_MAX_BYTES : input.byteLength >= BLOB_POINTER_MAX_BYTES)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(typeof input === 'string' ? input : new TextDecoder('utf-8', { fatal: true }).decode(input));
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const version = value['boring:blob'];
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1)
+        return undefined;
+    if (version > BLOB_POINTER_VERSION)
+        return { kind: 'unsupported-version', version };
+    const { id, sha256, size, type, name } = value;
+    if (!text(id, 512) || typeof sha256 !== 'string' || !SHA256.test(sha256) || typeof size !== 'number' || !Number.isSafeInteger(size) || size < 0
+        || typeof type !== 'string' || !MEDIA_TYPE.test(type) || !text(name, 255) || /[/\\]/.test(name) || name === '.' || name === '..')
+        return undefined;
+    return { 'boring:blob': 1, id, sha256, size, type, name };
+}
+/** Whether a workspace path names a pointer file (`*.blob.json`). */
+export const isBlobPointerPath = (path) => {
+    const name = path.slice(path.lastIndexOf('/') + 1).toLowerCase();
+    return name.length > BLOB_POINTER_SUFFIX.length && name.endsWith(BLOB_POINTER_SUFFIX);
+};
+/**
+ * The checked blob base: a same-origin path starting with one `/` (default `/_files/`). A URL with a scheme or host, a
+ * protocol-relative `//host`, a backslash, whitespace or a control character is refused with a `TypeError`.
+ */
+export function checkBlobBase(base = DEFAULT_BLOB_BASE) {
+    const origin = 'https://same-origin.invalid';
+    let resolved;
+    try {
+        resolved = new URL(base, origin);
+    }
+    catch {
+        resolved = undefined;
+    }
+    if (typeof base !== 'string' || !base.startsWith('/') || base.startsWith('//') || /[\\\s]/.test(base) || CONTROL.test(base) || resolved?.origin !== origin) {
+        throw new TypeError(`blobBase must be a same-origin path starting with "/", not ${JSON.stringify(base)}`);
+    }
+    return base;
+}
+/** The item a pointer stands for, with the URL of its bytes under a checked `base`. */
+export const blobItemOf = (pointer, base = DEFAULT_BLOB_BASE) => ({ name: pointer.name, size: pointer.size, type: pointer.type, url: `${checkBlobBase(base)}${encodeURIComponent(pointer.id)}` });
+/** A pointer file's bytes as what to show: `{ kind: 'blob', item }`, an unsupported version, or `undefined` (not a pointer: show the file). */
+export function resolveBlobPointer(input, base = DEFAULT_BLOB_BASE) {
+    const parsed = parseBlobPointer(input);
+    if (parsed === undefined || 'kind' in parsed)
+        return parsed;
+    return { kind: 'blob', item: blobItemOf(parsed, base) };
+}
+/**
+ * The provider as a listing reads it: each pointer file in a `list` or `search` page carries `blob` (the item it stands for, or its
+ * unsupported version), read once through the same provider. Every other call is the provider's own; reads still return the
+ * pointer's bytes, so a conditional write of the pointer file works as for any file. `base` is checked here, once.
+ */
+export function withBlobPointers(provider, base = DEFAULT_BLOB_BASE) {
+    checkBlobBase(base);
+    const resolve = async (page, signal) => ({ ...page, entries: await Promise.all(page.entries.map(async (entry) => {
+            if (entry.kind !== 'file' || !isBlobPointerPath(entry.path) || entry.size >= BLOB_POINTER_MAX_BYTES)
+                return entry;
+            try {
+                const read = await provider.read({ target: provider.locate(entry.path), revision: { kind: 'latest' } }, signal);
+                const resolved = read.kind === 'available' ? resolveBlobPointer(read.snapshot.bytes, base) : undefined;
+                return resolved === undefined ? entry : { ...entry, blob: resolved.kind === 'blob' ? resolved.item : resolved };
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                return entry;
+            }
+        })) });
+    return { ...provider, list: async (request, signal) => resolve(await provider.list(request, signal), signal), search: async (request, signal) => resolve(await provider.search(request, signal), signal) };
+}

package/dist/file-types.d.ts

@@ -9,11 +9,20 @@ export declare const extensionOf: (path: string) => string;
 export declare const MEDIA_TYPES: Readonly<Record<string, string>>;
 /** The IANA media type of a path, `application/octet-stream` when unknown. */
 export declare const mediaTypeOf: (path: string) => string;
-/** The media type a file's leading bytes name (a PDF, PNG, JPEG, GIF or WebP signature), or undefined. */
+/** How many leading bytes `sniffMediaType` looks at: a caller reads this many and passes them in. */
+export declare const SNIFF_BYTES = 8192;
+/**
+ * The media type a file's leading bytes name, or undefined. Pass up to `SNIFF_BYTES` of them.
+ *  - Signatures: PDF, PNG, JPEG, GIF, WebP, HEIC/HEIF and MP4/MOV/M4V (`ftyp` brands), WebM (EBML), and zip-based documents.
+ *  - Otherwise `text/plain` when the bytes are valid UTF-8 (a character cut at the end is allowed) with no NUL byte: a weak answer, a
+ *    name says better which text it is (`delimitedTextType` for CSV and TSV).
+ */
 export declare function sniffMediaType(head: Uint8Array): string | undefined;
+/** CSV or TSV: content alone cannot tell them from other text, so the name says which and the bytes must be text. Undefined otherwise. */
+export declare function delimitedTextType(path: string, head: Uint8Array): 'text/csv' | 'text/tab-separated-values' | undefined;
 /** Which viewer opens a file. Anything not listed is shown as text when it decodes. */
-export type ViewerKind = 'markdown' | 'html' | 'canvas' | 'image' | 'pdf' | 'text';
-/** The viewer kind of a path: `markdown`, `html`, `canvas`, `image`, `pdf` or `text`. */
+export type ViewerKind = 'markdown' | 'html' | 'canvas' | 'image' | 'pdf' | 'video' | 'text';
+/** The viewer kind of a path: `markdown`, `html`, `canvas`, `image`, `pdf`, `video` or `text`. */
 export declare const viewerKindOf: (path: string) => ViewerKind;
 /** Binary viewers never decode a file as text, whatever its bytes look like (an SVG is text). */
 export declare const isBinaryKind: (path: string) => boolean;

package/dist/file-types.js

@@ -8,8 +8,10 @@ export const extensionOf = (path) => { const dot = path.lastIndexOf('.'); return
 /** The IANA media type by extension. Anything not listed is `application/octet-stream` (see `mediaTypeOf`). Null-prototype: `constructor` or `__proto__` is not an entry. */
 export const MEDIA_TYPES = Object.assign(Object.create(null), {
     md: 'text/markdown', markdown: 'text/markdown', html: 'text/html', htm: 'text/html', json: 'application/json', svg: 'image/svg+xml',
-    txt: 'text/plain', csv: 'text/csv', js: 'text/javascript', mjs: 'text/javascript', css: 'text/css', tldraw: 'application/vnd.tldraw+json',
+    txt: 'text/plain', csv: 'text/csv', tsv: 'text/tab-separated-values', js: 'text/javascript', mjs: 'text/javascript', css: 'text/css', tldraw: 'application/vnd.tldraw+json',
     png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', bmp: 'image/bmp', tif: 'image/tiff', tiff: 'image/tiff',
+    heic: 'image/heic', heif: 'image/heif',
+    mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', m4v: 'video/x-m4v', ogg: 'video/ogg', ogv: 'video/ogg',
     pdf: 'application/pdf', doc: 'application/msword', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
     xls: 'application/vnd.ms-excel', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
     ppt: 'application/vnd.ms-powerpoint', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
@@ -18,7 +20,82 @@ export const MEDIA_TYPES = Object.assign(Object.create(null), {
 });
 /** The IANA media type of a path, `application/octet-stream` when unknown. */
 export const mediaTypeOf = (path) => MEDIA_TYPES[extensionOf(path)] ?? 'application/octet-stream';
-/** The media type a file's leading bytes name (a PDF, PNG, JPEG, GIF or WebP signature), or undefined. */
+/** How many leading bytes `sniffMediaType` looks at: a caller reads this many and passes them in. */
+export const SNIFF_BYTES = 8192;
+const ascii = (bytes) => String.fromCharCode(...bytes);
+const u16 = (bytes, at) => (bytes[at] ?? 0) | ((bytes[at + 1] ?? 0) << 8);
+const u32 = (bytes, at) => (u16(bytes, at) | (u16(bytes, at + 2) << 16)) >>> 0;
+const HEIC_BRANDS = new Set(['heic', 'heix', 'hevc', 'hevx', 'heim', 'heis']);
+const HEIF_BRANDS = new Set(['mif1', 'msf1', 'heif']);
+const MP4_BRANDS = new Set(['isom', 'iso2', 'iso3', 'iso4', 'iso5', 'iso6', 'mp41', 'mp42', 'avc1', 'dash']);
+/**
+ * HEIC/HEIF by their ISO-BMFF `ftyp` box: a HEVC brand (`heic`, `heix`, `hevc`, …) is HEIC; the generic image brands (`mif1`, `msf1`)
+ * are HEIC when a compatible brand says HEVC, HEIF otherwise, and nothing when a compatible brand says AVIF (not claimed here).
+ */
+function sniffHeif(head) {
+    if (head.length < 16 || ascii(head.subarray(4, 8)) !== 'ftyp')
+        return undefined;
+    const major = ascii(head.subarray(8, 12));
+    const end = Math.min(head.length, Math.max(16, (head[0] << 24 | head[1] << 16 | head[2] << 8 | head[3]) >>> 0));
+    const compatible = new Set();
+    for (let at = 16; at + 4 <= end; at += 4)
+        compatible.add(ascii(head.subarray(at, at + 4)));
+    if (HEIC_BRANDS.has(major))
+        return 'image/heic';
+    if (!HEIF_BRANDS.has(major))
+        return undefined;
+    if (compatible.has('avif') || compatible.has('avis'))
+        return undefined;
+    return [...compatible].some(brand => HEIC_BRANDS.has(brand)) ? 'image/heic' : 'image/heif';
+}
+const OOXML_MAIN = [
+    ['wordprocessingml.document.main', 'word/', MEDIA_TYPES.docx],
+    ['spreadsheetml.sheet.main', 'xl/', MEDIA_TYPES.xlsx],
+    ['presentationml.presentation.main', 'ppt/', MEDIA_TYPES.pptx],
+];
+const ZIP_MIMETYPES = new Set([MEDIA_TYPES.odt, MEDIA_TYPES.ods, MEDIA_TYPES.odp, MEDIA_TYPES.epub]);
+/**
+ * Zip-based documents from the head alone, without inflating anything: it walks the local file headers that fit in `head`.
+ *  - OpenDocument and EPUB: a first entry `mimetype`, stored uncompressed, holds the media type itself.
+ *  - Office Open XML (docx, xlsx, pptx): a `[Content_Types].xml` entry, then the main part's content type when that entry is stored
+ *    uncompressed, or else the folder of a later entry (`word/`, `xl/`, `ppt/`). Its content is almost always deflated, and inflating
+ *    is asynchronous in a browser, so the folder rule is the usual one.
+ * A zip whose entries have unknown sizes (a data descriptor) cannot be walked past its first entry; it is then not claimed.
+ */
+function sniffZip(head) {
+    let contentTypes = false;
+    for (let offset = 0, index = 0; index < 64 && offset + 30 <= head.length && u32(head, offset) === 0x04034b50; index++) {
+        const flags = u16(head, offset + 6), method = u16(head, offset + 8), size = u32(head, offset + 18);
+        const nameStart = offset + 30, nameEnd = nameStart + u16(head, offset + 26), dataStart = nameEnd + u16(head, offset + 28);
+        if (nameEnd > head.length)
+            return undefined;
+        const name = ascii(head.subarray(nameStart, nameEnd));
+        const stored = method === 0 && (flags & 8) === 0 && dataStart + size <= head.length ? ascii(head.subarray(dataStart, dataStart + size)) : undefined;
+        if (index === 0 && name === 'mimetype' && stored !== undefined)
+            return ZIP_MIMETYPES.has(stored.trim()) ? stored.trim() : undefined;
+        if (name === '[Content_Types].xml') {
+            contentTypes = true;
+            const named = stored === undefined ? undefined : OOXML_MAIN.find(([main]) => stored.includes(`${main}+xml`));
+            if (named)
+                return named[2];
+        }
+        else if (contentTypes) {
+            const folder = OOXML_MAIN.find(([, prefix]) => name.startsWith(prefix));
+            if (folder)
+                return folder[2];
+        }
+        if (flags & 8)
+            return undefined;
+        offset = dataStart + size;
+    }
+    return undefined;
+}
+/**
+ * The media type a file's leading bytes name, or undefined. Pass up to `SNIFF_BYTES` of them.
+ *  - Signatures: PDF, PNG, JPEG, GIF, WebP, HEIC/HEIF and MP4/MOV/M4V (`ftyp` brands), WebM (EBML), and zip-based documents.
+ *  - Otherwise `text/plain` when the bytes are valid UTF-8 (a character cut at the end is allowed) with no NUL byte: a weak answer, a
+ *    name says better which text it is (`delimitedTextType` for CSV and TSV).
+ */
 export function sniffMediaType(head) {
     const at = (signature, offset = 0) => signature.every((byte, index) => head[offset + index] === byte);
     if (at([0x25, 0x50, 0x44, 0x46, 0x2d]))
@@ -31,17 +108,52 @@ export function sniffMediaType(head) {
         return 'image/gif';
     if (at([0x52, 0x49, 0x46, 0x46]) && at([0x57, 0x45, 0x42, 0x50], 8))
         return 'image/webp';
-    return undefined;
+    const heif = sniffHeif(head);
+    if (heif)
+        return heif;
+    if (head.length >= 16 && ascii(head.subarray(4, 8)) === 'ftyp') {
+        const brand = ascii(head.subarray(8, 12));
+        if (brand === 'qt  ')
+            return 'video/quicktime';
+        if (brand === 'M4V ' || brand === 'M4VH' || brand === 'M4VP')
+            return 'video/x-m4v';
+        if (MP4_BRANDS.has(brand))
+            return 'video/mp4';
+    }
+    if (at([0x1a, 0x45, 0xdf, 0xa3]))
+        return 'video/webm';
+    if (at([0x50, 0x4b, 0x03, 0x04]))
+        return sniffZip(head.subarray(0, SNIFF_BYTES));
+    const sample = head.subarray(0, SNIFF_BYTES);
+    if (sample.length === 0 || sample.includes(0))
+        return undefined;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(sample, { stream: true });
+        return 'text/plain';
+    }
+    catch {
+        return undefined;
+    }
+}
+/** CSV or TSV: content alone cannot tell them from other text, so the name says which and the bytes must be text. Undefined otherwise. */
+export function delimitedTextType(path, head) {
+    const extension = extensionOf(path);
+    if (extension !== 'csv' && extension !== 'tsv')
+        return undefined;
+    if (sniffMediaType(head) !== 'text/plain')
+        return undefined;
+    return extension === 'csv' ? 'text/csv' : 'text/tab-separated-values';
 }
 const VIEWER_KINDS = Object.assign(Object.create(null), {
     md: 'markdown', markdown: 'markdown', html: 'html', htm: 'html', tldraw: 'canvas',
     png: 'image', jpg: 'image', jpeg: 'image', gif: 'image', webp: 'image', svg: 'image', pdf: 'pdf',
+    mp4: 'video', webm: 'video', mov: 'video', m4v: 'video', ogg: 'video', ogv: 'video',
     txt: 'text', json: 'text', csv: 'text', js: 'text', mjs: 'text', css: 'text',
 });
-/** The viewer kind of a path: `markdown`, `html`, `canvas`, `image`, `pdf` or `text`. */
+/** The viewer kind of a path: `markdown`, `html`, `canvas`, `image`, `pdf`, `video` or `text`. */
 export const viewerKindOf = (path) => VIEWER_KINDS[extensionOf(path)] ?? 'text';
 /** Binary viewers never decode a file as text, whatever its bytes look like (an SVG is text). */
-export const isBinaryKind = (path) => ['image', 'pdf'].includes(viewerKindOf(path)) && extensionOf(path) !== 'svg';
+export const isBinaryKind = (path) => ['image', 'pdf', 'video'].includes(viewerKindOf(path)) && extensionOf(path) !== 'svg';
 /** The provider's temporary files are named `.boring-<uuid>.tmp` beside their target. They are removed when the provider opens and are never a resource. */
 const temporaryPattern = /^\.boring-[0-9a-f-]{36}\.tmp$/;
 /** The basename of a new temporary file, for a provider's `uuid`. */

package/dist/revision-contracts.d.ts

@@ -2,10 +2,25 @@ import type { ResourceClient } from './client.js';
 import type { ResourceAccess, ResourceLocator } from './contracts.js';
 import type { ResourceIdentity } from './remote-protocol.js';
 import type { WorkspaceKey } from './workspace-identity.js';
+/** What a viewer or a listing shows for a blob pointer (`./blob`): never the pointer itself. */
+export interface BlobItem {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    /** Same-origin URL of the bytes: `<blobBase><encodeURIComponent(id)>`. */
+    readonly url: string;
+}
+/** A blob pointer written in a newer format than `./blob` reads: show it as its JSON file, and say it is a newer format. */
+export interface UnsupportedBlobPointer {
+    readonly kind: 'unsupported-version';
+    readonly version: number;
+}
 export interface FileEntry {
     readonly path: string;
     readonly kind: 'file' | 'directory';
     readonly size: number;
+    /** A pointer file (`*.blob.json`) as a listing shows it: the item it stands for, or its unsupported version. Set by `withBlobPointers` (`./blob`), never by the protocol. */
+    readonly blob?: BlobItem | UnsupportedBlobPointer;
 }
 export interface FilePage {
     readonly entries: readonly FileEntry[];
@@ -81,7 +96,8 @@ export interface RevisionProvider extends ResourceClient {
     readonly history: (path: string, signal?: AbortSignal) => Promise<readonly SavedRevision[]>;
     /**
      * The workspace's change feed (`GET ?op=changes`, server-sent events), reconnecting after the last `seq` seen until `signal`
-     * aborts; a refused binding (another workspace, revoked access) ends it with a `RevisionError`. Optional: a hand-built provider
+     * aborts; a refused binding (another workspace, revoked access) ends it with a `RevisionError`, and so does a route that serves no feed:
+     * it answers 501 (the intended signal) or 400 to `?op=changes`, and the views then keep their own refresh. Optional: a hand-built provider
      * may have none, and a viewer then refreshes on its own schedule.
      */
     readonly changes?: (request?: ChangeFeedRequest) => AsyncIterable<WorkspaceChangeEvent>;

package/dist/revision.js

@@ -81,8 +81,9 @@ export async function connectRevisionProvider(options) {
                     void response.body?.cancel().catch(() => { });
                     if (response.status === 403 || response.status === 409)
                         throw new RevisionError('denied', 'The selected workspace is unavailable or no longer authorized');
-                    if (response.status === 400)
-                        throw new RevisionError('invalid', 'The change feed request was refused');
+                    // 501: the route serves no change feed (the intended signal); 400 is the same ending, kept for hosts that already answer it.
+                    if (response.status === 400 || response.status === 501)
+                        throw new RevisionError('invalid', response.status === 501 ? 'The route serves no change feed' : 'The change feed request was refused');
                     await pause();
                     continue;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-files",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -85,6 +85,10 @@
     "./file-types": {
       "types": "./dist/file-types.d.ts",
       "import": "./dist/file-types.js"
+    },
+    "./blob": {
+      "types": "./dist/blob.d.ts",
+      "import": "./dist/blob.js"
     }
   },
   "peerDependencies": {