db/file_fact_url.ts

Canonical filesystem-fact URL shape + on-disk layout.

external_url on the generic fact row is string | null because the FactStore interface stays federation-friendly (future https://... / s3://... shapes). Filesystem-minted URLs are exactly file:<shard>/<rest> where <shard> is the first 2 hex chars of the blake3 digest and <rest> the remaining 62 — files land at <facts_dir>/<shard>/<rest> after the writer atomically temp+renames them in.

Centralizing the regex + the fact_disk_path split keeps the shape in one place: PgFactStore's disk CAS (db/fact_disk_storage.ts), the serve_fact_route defense-in-depth check, and the file_fact_fetcher resolver all derive the layout here, so the write path and the read path can't drift. The TS twin of the Rust fact_disk_path (fuz_fact).

Defense-in-depth: a .. segment can't match (. isn't in [0-9a-f]), neither can absolute paths, query strings, or any non-hex character. Used in front of path.join so the resolver never trusts the URL came from a fact row, even though it always does in practice.

view source

Declarations
#

6 declarations

fact_disk_path
#

db/file_fact_url.ts view source

(hash: string & $brand<"FactHash">): { shard: string; rest: string; } import {fact_disk_path} from '@fuzdev/fuz_app/db/file_fact_url.js';

Split a FactHash into its on-disk <shard>/<rest> parts — the first 2 hex chars of the digest (shard subdir) + the remaining 62. The single source of truth for the disk layout, so the write path (put / put_stream) and the URL minted into the fact row can't disagree. Mirrors the Rust fact_disk_path in fuz_fact.

hash

type string & $brand<"FactHash">

returns

{ shard: string; rest: string; }

FILE_FACT_URL_PATTERN
#

db/file_fact_url.ts view source

RegExp import {FILE_FACT_URL_PATTERN} from '@fuzdev/fuz_app/db/file_fact_url.js';

Anchored, capture-group form: ^file:(<shard>)/(<rest>)$.

FileFactUrl
#

is_file_fact_url
#

db/file_fact_url.ts view source

(s: string): s is string & $brand<"FileFactUrl"> import {is_file_fact_url} from '@fuzdev/fuz_app/db/file_fact_url.js';

Type guard. Useful when discriminating a string | null column.

s

type string

returns

boolean

mint_file_fact_url
#

db/file_fact_url.ts view source

(shard: string, rest: string): string & $brand<"FileFactUrl"> import {mint_file_fact_url} from '@fuzdev/fuz_app/db/file_fact_url.js';

Construct a canonical file:<shard>/<rest> URL. The writer side (db/fact_disk_storage.ts) assembles the shape from a freshly-computed hash via fact_disk_path; this helper centralizes the literal so a future shape change is a single edit.

shard

type string

rest

type string

returns

string & $brand<"FileFactUrl">

parse_file_fact_url
#

db/file_fact_url.ts view source

(url: string): { url: string & $brand<"FileFactUrl">; shard: string; rest: string; } | null import {parse_file_fact_url} from '@fuzdev/fuz_app/db/file_fact_url.js';

Validate a string against the canonical shape. Returns the branded URL plus its parsed parts, or null on shape mismatch — callers decide whether that's a 404 (read), a skip (GC), or a hard reject (write).

url

type string

returns

{ url: string & $brand<"FileFactUrl">; shard: string; rest: string; } | null

Imported by
#