@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/site.js

@@ -0,0 +1,169 @@
+// Site files: sitemap.xml, an Atom feed, _redirects and _headers (SITEMAP, FEED,
+// REDIRECT, HEADER; docs/LANGUAGE.md "Site files"). Ported as rust/src/site.rs:
+// both must produce the same bytes and messages.
+import { SitefileError } from './errors.js';
+/** ASCII whitespace, other control characters, and DEL. */
+const SPACE_OR_CONTROL = /[\u0000- \u007f]/;
+/** Control characters other than tab. */
+const CONTROL = /[\u0000-\u0008\u000a-\u001f\u007f]/;
+/** An RFC 9110 token (header names). */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * Check a SITEMAP/FEED `BASE`: an absolute http(s) URL with a host and no credentials,
+ * query, fragment, whitespace or control characters. Returns it without trailing slashes.
+ */
+export function checkBaseUrl(raw, what, span) {
+    const m = /^https?:\/\/([^/]*)/i.exec(raw);
+    if (!m || m[1] === '' || m[1].includes('@') || /[\u0000- \u007f?#]/.test(raw)) {
+        throw new SitefileError('E_VALIDATION', `${what} '${raw}' must be an absolute http(s) URL such as https://example.com (no credentials, query or fragment)`, span);
+    }
+    return raw.replace(/\/+$/, '');
+}
+/** `<base><path>` with each segment percent-encoded; `…/index.html` becomes its directory URL `…/`. */
+export function pageUrl(base, path) {
+    const p = path.endsWith('/index.html') ? path.slice(0, -'index.html'.length) : path;
+    return base + p.split('/').map(encodeURIComponent).join('/');
+}
+/** Escape text for XML content and attribute values; characters XML 1.0 forbids become U+FFFD. */
+export function xmlEscape(s) {
+    return s.replace(/[&<>"'\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, (c) => c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : c === "'" ? '&apos;' : '�');
+}
+function utf8Compare(a, b) {
+    return Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+}
+/** sitemaps.org XML for every `.html` file in the tree except `/404.html`, sorted by path. */
+export function sitemapXml(tree, base) {
+    const paths = tree
+        .entries()
+        .map(([p]) => p)
+        .filter((p) => p.endsWith('.html') && p !== '/404.html')
+        .sort(utf8Compare);
+    let out = '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';
+    for (const p of paths)
+        out += `  <url><loc>${xmlEscape(pageUrl(base, p))}</loc></url>\n`;
+    return out + '</urlset>\n';
+}
+function daysFromCivil(y, m, d) {
+    const yy = m <= 2 ? y - 1 : y;
+    const era = Math.floor(yy / 400);
+    const yoe = yy - era * 400;
+    const doy = Math.floor((153 * (m + (m > 2 ? -3 : 9)) + 2) / 5) + d - 1;
+    const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+    return era * 146097 + doe - 719468;
+}
+function daysInMonth(y, m) {
+    if (m === 2)
+        return (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0 ? 29 : 28;
+    return [4, 6, 9, 11].includes(m) ? 30 : 31;
+}
+/** `YYYY-MM-DD` (midnight UTC) or an RFC 3339 date-time; undefined when it is neither. */
+export function parseFeedDate(s) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?([Zz]|[+-]\d{2}:\d{2}))?$/.exec(s);
+    if (!m)
+        return undefined;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    if (mo < 1 || mo > 12 || d < 1 || d > daysInMonth(y, mo))
+        return undefined;
+    const date = `${m[1]}-${m[2]}-${m[3]}`;
+    if (m[4] === undefined)
+        return { text: `${date}T00:00:00Z`, seconds: daysFromCivil(y, mo, d) * 86400, fraction: '000000000' };
+    const [h, mi, sec] = [Number(m[4]), Number(m[5]), Number(m[6] ?? '0')];
+    if (h > 23 || mi > 59 || sec > 59)
+        return undefined;
+    const zone = m[8].toUpperCase();
+    let offset = 0;
+    if (zone !== 'Z') {
+        const [oh, om] = [Number(zone.slice(1, 3)), Number(zone.slice(4, 6))];
+        if (oh > 23 || om > 59)
+            return undefined;
+        offset = (zone[0] === '-' ? -1 : 1) * (oh * 3600 + om * 60);
+    }
+    const frac = m[7] ?? '';
+    const text = `${date}T${m[4]}:${m[5]}:${m[6] ?? '00'}${frac}${zone}`;
+    const seconds = daysFromCivil(y, mo, d) * 86400 + h * 3600 + mi * 60 + sec - offset;
+    return { text, seconds, fraction: (frac.slice(1) + '000000000').slice(0, 9) };
+}
+function newer(a, b) {
+    return a.seconds > b.seconds || (a.seconds === b.seconds && a.fraction > b.fraction);
+}
+/** Atom 1.0. The feed's id is its own URL; each entry's id is its link. */
+export function atomXml(feed) {
+    let updated;
+    for (const e of feed.entries)
+        if (!updated || newer(e.date, updated))
+            updated = e.date;
+    const x = xmlEscape;
+    let out = '<?xml version="1.0" encoding="utf-8"?>\n<feed xmlns="http://www.w3.org/2005/Atom">\n';
+    out += `  <title>${x(feed.title)}</title>\n`;
+    out += `  <link href="${x(feed.siteUrl)}"/>\n`;
+    out += `  <link rel="self" href="${x(feed.selfUrl)}"/>\n`;
+    out += `  <id>${x(feed.selfUrl)}</id>\n`;
+    out += `  <updated>${updated?.text ?? '1970-01-01T00:00:00Z'}</updated>\n`;
+    for (const e of feed.entries) {
+        out += '  <entry>\n';
+        out += `    <title>${x(e.title)}</title>\n`;
+        out += `    <link href="${x(e.url)}"/>\n`;
+        out += `    <id>${x(e.url)}</id>\n`;
+        out += `    <updated>${e.date.text}</updated>\n`;
+        if (e.author !== undefined)
+            out += `    <author><name>${x(e.author)}</name></author>\n`;
+        if (e.summary !== undefined)
+            out += `    <summary>${x(e.summary)}</summary>\n`;
+        if (e.content !== undefined)
+            out += `    <content type="html">${x(e.content)}</content>\n`;
+        out += '  </entry>\n';
+    }
+    return out + '</feed>\n';
+}
+/** Check a REDIRECT source (`from`) or HEADER pattern: an absolute path with no spaces or control characters. */
+export function checkSitePath(raw, what, span) {
+    if (SPACE_OR_CONTROL.test(raw))
+        throw new SitefileError('E_VALIDATION', `${what} must not contain spaces or control characters`, span);
+    if (!raw.startsWith('/'))
+        throw new SitefileError('E_VALIDATION', `${what} '${raw}' must be an absolute path starting with '/'`, span);
+    return raw;
+}
+/** Check a REDIRECT target: an absolute path or an http(s) URL. */
+export function checkRedirectTarget(raw, span) {
+    if (SPACE_OR_CONTROL.test(raw))
+        throw new SitefileError('E_VALIDATION', 'REDIRECT target must not contain spaces or control characters', span);
+    if (!raw.startsWith('/') && !/^https?:\/\/[^/]/i.test(raw)) {
+        throw new SitefileError('E_VALIDATION', `REDIRECT target '${raw}' must be an absolute path or an http(s) URL`, span);
+    }
+    return raw;
+}
+export function checkHeaderName(raw, span) {
+    if (SPACE_OR_CONTROL.test(raw))
+        throw new SitefileError('E_VALIDATION', 'HEADER name must not contain spaces or control characters', span);
+    if (!TOKEN.test(raw)) {
+        throw new SitefileError('E_VALIDATION', `HEADER name '${raw}' is not a valid header name (letters, digits and !#$%&'*+-.^_\`|~)`, span);
+    }
+    return raw;
+}
+/** The header value: trimmed of spaces and tabs; non-empty, no control characters other than tab. */
+export function checkHeaderValue(raw, name, span) {
+    if (CONTROL.test(raw))
+        throw new SitefileError('E_VALIDATION', `HEADER ${name}: the value must not contain control characters (CR, LF, …)`, span);
+    const v = raw.replace(/^[ \t]+|[ \t]+$/g, '');
+    if (v === '')
+        throw new SitefileError('E_VALIDATION', `HEADER ${name}: the value is empty`, span);
+    return v;
+}
+/** `/_redirects` in the Netlify / Cloudflare Pages format: `from to status`, one per line, in source order. */
+export function redirectsFile(rules) {
+    return rules.map((r) => `${r.from} ${r.to} ${r.status}\n`).join('');
+}
+/** `/_headers`: one block per path pattern (in order of first use), its headers indented in source order. */
+export function headersFile(rules) {
+    const blocks = new Map();
+    for (const r of rules) {
+        const b = blocks.get(r.pattern) ?? [];
+        b.push(`  ${r.name}: ${r.value}\n`);
+        blocks.set(r.pattern, b);
+    }
+    let out = '';
+    for (const [pattern, lines] of blocks)
+        out += `${pattern}\n${lines.join('')}`;
+    return out;
+}
+//# sourceMappingURL=site.js.map

package/lib/src/store.d.ts

@@ -0,0 +1,151 @@
+import type { Readable } from 'node:stream';
+import { type Referrer, type ReferrerDescriptor } from './attest.js';
+import { type OciOptions, type ParsedConfig, type ParsedManifest } from './oci.js';
+import { type ImageRef } from './ref.js';
+import type { Tree } from './tree.js';
+/**
+ * The local image store IS an OCI image layout (image-spec v1.1) at $SITEFILE_HOME (default ~/.sitefile):
+ *
+ *   oci-layout           {"imageLayoutVersion":"1.0.0"}
+ *   index.json           image index. Each entry is a manifest descriptor; tags are entries annotated
+ *                        org.opencontainers.image.ref.name = "name:tag". An image with no tag is a
+ *                        "dangling" entry without that annotation. dev.sitefile.created records when
+ *                        the image was first stored (bookkeeping only; no digest depends on it).
+ *   blobs/sha256/<hex>   manifest, config and layer blobs (identical layers share a blob)
+ *   referrers/sha256/<hex>  attestations of image <hex> (`build -t --provenance/--sbom`): an OCI image
+ *                        index of artifact manifests whose subject is that image (their blobs are in blobs/)
+ *   servers/             site server state and logs (see servers.ts)
+ *   lock                 advisory lock for mutations
+ *
+ * IMAGE ID = the manifest digest. All writes are temp file + rename, mutations hold the lock, and every
+ * blob is digest-verified when read (corruption is E_STORE).
+ */
+export interface ImageSummary {
+    /** Full `sha256:<hex>` image ID (the manifest digest). */
+    readonly id: string;
+    readonly tags: readonly string[];
+    /** When the image was first stored. */
+    readonly created: string;
+    readonly files: number;
+    /** Total bytes of the site's files (uncompressed). */
+    readonly size: number;
+}
+export interface ImageDetails extends ImageSummary {
+    readonly manifest: ParsedManifest;
+    readonly config: ParsedConfig;
+    readonly root: string;
+    /** Compressed layer size in bytes. */
+    readonly layerSize: number;
+}
+export declare function resolveStoreHome(env?: NodeJS.ProcessEnv): string;
+export declare function shortId(id: string): string;
+export declare class Store {
+    readonly home: string;
+    private constructor();
+    /** The store at `home` if one exists there (nothing is created). */
+    static openExisting(home?: string): Promise<Store | undefined>;
+    static open(home?: string): Promise<Store>;
+    private blobFile;
+    /** Run `fn` holding the store lock (an exclusive lock file; stale locks are broken). */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+    private lockIsStale;
+    private writeAtomic;
+    private readIndex;
+    /** Normalize (one dangling entry per untagged image, none for tagged ones), sort, write. */
+    private writeIndex;
+    /** `name:tag` → image ID. */
+    refs(): Promise<Record<string, string>>;
+    /** Read a blob and verify its digest (and size when given). */
+    readBlob(digest: string, size?: number): Promise<Uint8Array>;
+    private putBlob;
+    /**
+     * Mark a blob as just used (its mtime is the recency the size limit goes by, see cache-limit.ts;
+     * atime is often disabled). Never fails.
+     */
+    touchBlob(digest: string): Promise<void>;
+    /** True when the blob exists with the given size (content is verified when it was written). */
+    hasBlob(digest: string, size?: number): Promise<boolean>;
+    /** Stream a stored blob (for upload); write-time verification means no re-hash here. */
+    blobStream(digest: string): Readable;
+    /**
+     * Store a blob from a stream, verifying its size and sha256 while it is written (to a temp file
+     * that is renamed into place only when both match). `maxBytes` bounds what is accepted.
+     */
+    importBlob(digest: string, size: number, source: AsyncIterable<Uint8Array>, maxBytes?: number): Promise<void>;
+    /** Store a small blob (manifest, config, index) given its bytes; the digest is computed. */
+    putSmallBlob(bytes: Uint8Array): Promise<string>;
+    /**
+     * Register a pulled image manifest (all its blobs must already be stored): it becomes an index
+     * entry, optionally tagged with `key` (replacing that tag's previous target).
+     */
+    addManifest(manifestBytes: Uint8Array, tagRef?: ImageRef, now?: Date): Promise<string>;
+    /** Whether an image with this manifest digest is in the index. */
+    hasImage(id: string): Promise<boolean>;
+    /** Store a tree as an OCI image (idempotent: identical content and options give the same ID). Untagged. */
+    addImage(tree: Tree, options?: OciOptions, now?: Date): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /** Manifest and config of an image, digest-verified (not its layer). */
+    details(id: string): Promise<ImageDetails>;
+    /**
+     * Load an image's files (under its root, or under `o.root`), verifying manifest, config, layer digest
+     * and diff_id. `o.origin` is what the files' origins and error messages name (default `image:<short id>`).
+     */
+    loadTree(id: string, o?: {
+        readonly origin?: string;
+        readonly root?: string;
+    }): Promise<Tree>;
+    /**
+     * The image as a standalone OCI layout Tree (for `save`), optionally annotated with a tag.
+     * Includes every layer, so an image built on a BASE is self-contained.
+     */
+    layoutOf(id: string, refName?: string): Promise<Tree>;
+    private referrersFile;
+    /** Descriptors of the attestations stored for image `id` (none: empty). */
+    referrerDescriptors(id: string): Promise<ReferrerDescriptor[]>;
+    /** The attestations stored for image `id`, with their blobs (digest-verified). */
+    referrers(id: string): Promise<Referrer[]>;
+    /**
+     * Attach attestations to stored image `id`: their blobs are written, and each replaces a stored
+     * attestation with the same predicate type (others are kept).
+     */
+    putReferrers(id: string, referrers: readonly Referrer[]): Promise<void>;
+    /** Blob hexes of the attestations of `id` (manifests, configs, layers); unreadable ones count as none. */
+    private referrerBlobHexes;
+    /** Every stored image, newest first. */
+    list(): Promise<ImageSummary[]>;
+    private idsWithPrefix;
+    /** Resolve a reference or (short) image ID to a full image ID. */
+    resolve(input: string): Promise<string>;
+    /** Point `name:tag` at an image (replacing any previous target). Returns the `name:tag` key. */
+    tag(id: string, ref: ImageRef): Promise<string>;
+    /**
+     * `rmi`: remove a tag, or an image by ID. The image leaves the index when no tag references it
+     * (blobs are reclaimed by `prune`). Removing by ID while several tags point at it needs `force`.
+     */
+    removeImage(input: string, force?: boolean): Promise<{
+        untagged: string[];
+        deleted: string | undefined;
+    }>;
+    /**
+     * What the size limit may evict: `live` holds the blob hexes of tagged images (never evicted),
+     * `untagged` each untagged image with the blobs it uses. An unreadable tagged manifest throws
+     * (its blobs are unknown, so nothing may be evicted).
+     */
+    gcView(): Promise<{
+        live: Set<string>;
+        untagged: Array<{
+            id: string;
+            blobs: string[];
+        }>;
+    }>;
+    /** Remove an untagged image from the index, with its attestation list (its blobs stay). The caller holds the lock. */
+    dropUntaggedLocked(id: string): Promise<void>;
+    /** Drop untagged images from the index, then delete every blob no remaining image uses. */
+    prune(): Promise<{
+        manifests: number;
+        blobs: number;
+        bytes: number;
+    }>;
+}