git-fs-s3 0.4.0 → 0.5.0

package/dist/http.d.ts

@@ -1,215 +0,0 @@
-import { R as Repo } from './types-BHoHOaQt.js';
-import 'isomorphic-git';
-
-/**
- * Transport-agnostic HTTP response the handlers produce.
- *
- * `body` is pinned to `Uint8Array<ArrayBuffer>` (not the bare `Uint8Array`,
- * whose default type argument isn't consistent across TypeScript versions)
- * so it's always assignable to Fetch API `BodyInit` regardless of which
- * TypeScript/lib version a consumer compiles against — every producer here
- * (`concat`, `pktLine`, `TextEncoder.encode`) is ArrayBuffer-backed already.
- */
-interface GitHttpResult {
-    status: number;
-    headers: Record<string, string>;
-    body: Uint8Array<ArrayBuffer>;
-}
-/** Optional instrumentation hooks shared by the /http handlers. */
-interface HttpHooks {
-    /** Wrap a timed sub-step. Default: run directly. */
-    step?: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
-    /** Non-fatal problem sink (missing objects, failed repacks). */
-    onWarn?: (message: string, error?: unknown) => void;
-}
-/**
- * The raw promise-fs surface some /http paths need beyond isomorphic-git's
- * plumbing (writing an incoming pack file, listing/deleting pack files).
- * Both `node:fs` and this package's `GitFs` satisfy it via `.promises`.
- */
-interface RawFsPromises {
-    readFile(path: string): Promise<Uint8Array | string>;
-    writeFile(path: string, data: Uint8Array | string): Promise<void>;
-    unlink(path: string): Promise<void>;
-    readdir(path: string): Promise<string[]>;
-    mkdir(path: string, options?: {
-        recursive?: boolean;
-    }): Promise<unknown>;
-    stat(path: string): Promise<unknown>;
-}
-/** Duck-type the `.promises` surface off a repo's fs. */
-declare function rawFs(repo: Repo): RawFsPromises;
-
-type GitService = "git-upload-pack" | "git-receive-pack";
-/** All refs with resolved oids, plus the symref HEAD should advertise. */
-declare function listAllRefs(repo: Repo, defaultBranch?: string): Promise<{
-    refs: {
-        name: string;
-        oid: string;
-    }[];
-    headSymref: string;
-}>;
-interface InfoRefsOptions {
-    service: GitService;
-    defaultBranch?: string;
-    /** Advertised in the agent capability. Default "git-fs-s3". */
-    agent?: string;
-}
-/**
- * `GET …/info/refs?service=…` — the ref advertisement. Authentication and
- * authorization are the caller's job before invoking this.
- *
- * Capabilities advertised match what the sibling handlers implement:
- * side-band-64k (honored by handleUploadPack's response framing — clients
- * like isomorphic-git unconditionally expect it), tip/reachable sha1 wants,
- * delete-refs and report-status for pushes.
- */
-declare function handleInfoRefs(repo: Repo, options: InfoRefsOptions, hooks?: HttpHooks): Promise<GitHttpResult>;
-
-/**
- * Git pkt-line framing (smart HTTP protocol wire format).
- *
- * Edge-compatible: uses Uint8Array instead of Buffer.
- */
-/** Flush packet: exactly four zero bytes. */
-declare const FLUSH: Uint8Array<ArrayBuffer>;
-/** Frame a UTF-8 string as one pkt-line. */
-declare function pktLine(data: string): Uint8Array<ArrayBuffer>;
-/** Frame raw bytes as one pkt-line. */
-declare function pktLineBuffer(body: Uint8Array): Uint8Array<ArrayBuffer>;
-/** Decode pkt-lines to strings; `null` marks a flush-pkt. Stops on garbage. */
-declare function parsePktLines(buf: Uint8Array): Array<string | null>;
-declare function sideBandPackfile(packData: Uint8Array): Uint8Array<ArrayBuffer>;
-
-interface ReachabilityResult {
-    oids: string[];
-    /**
-     * False if any object in the graph couldn't be read — repack uses this
-     * (not a raw object-count comparison) to decide whether it's safe to
-     * delete old packs: counts alone can't distinguish "everything read fine"
-     * from "some objects silently failed".
-     */
-    complete: boolean;
-}
-/**
- * Walk the object graph from `startOids`, returning every reachable oid.
- * Concurrent traversal paths are deduplicated promise-per-oid; a missing
- * object is retried once, then reported through `hooks.onWarn` and
- * reflected in `complete: false`.
- *
- * `haveOids` bounds the walk: any oid in this set is assumed already
- * verified (it was reachable from a ref that existed before this call) and
- * is recorded in `seen` without being read or descended into. Without a
- * boundary, every call re-walks the *entire* history from scratch — for
- * receive-pack validation (see receive-pack.ts) that means every push pays
- * for reading every object in the repo, not just the ones it introduced,
- * and one transient read failure anywhere in that whole history rejects an
- * otherwise-valid push.
- *
- * Commits, trees and tags are read once each (parsed). Blobs have no
- * children, so `verifyBlobs: false` records a blob from its tree entry
- * without reading (and inflating) it — for callers that read every blob
- * themselves afterwards anyway, like upload-pack's `packObjects`. Leave it
- * true wherever the walk *is* the existence check (receive-pack, repack).
- */
-declare function collectReachableOids(repo: Repo, startOids: string[], hooks?: HttpHooks, haveOids?: ReadonlySet<string> | readonly string[], options?: {
-    verifyBlobs?: boolean;
-}): Promise<ReachabilityResult>;
-
-/**
- * Pack consolidation: merge all packs into one, reusing stored (possibly
- * deltified) entries when every object is packed.
- *
- * Edge-compatible: uses Web Crypto (SHA-1), CompressionStream (deflate),
- * and Uint8Array throughout — no node:crypto, node:zlib, or Buffer.
- */
-
-/**
- * Default repack threshold. Consolidating is O(total repo object count) —
- * so paying it on every push makes push latency grow with repo size forever.
- */
-declare const REPACK_PACK_COUNT_THRESHOLD = 4;
-interface RepackOptions {
-    /** Skip repacking below this many accumulated packs. Default 4. */
-    threshold?: number;
-}
-/**
- * Consolidate all pack files into one, returning the gitdir-relative paths
- * of the old .pack/.idx files it removed — after syncing the new pack to any
- * secondary storage, delete those same paths there too.
- */
-declare function repackRepository(repo: Repo, options?: RepackOptions, hooks?: HttpHooks): Promise<string[]>;
-
-interface RefUpdateCommand {
-    oldOid: string;
-    newOid: string;
-    refName: string;
-}
-interface RefUpdateResult {
-    refName: string;
-    ok: boolean;
-    reason?: string;
-}
-/** Split a receive-pack body: pkt-line ref commands, flush, then raw PACK. */
-declare function parseReceivePackBody(body: Uint8Array): {
-    refUpdates: RefUpdateCommand[];
-    packData: Uint8Array;
-};
-/** Initialize the repo when its HEAD doesn't exist yet (first push). */
-declare function ensureRepoInitialized(repo: Repo, defaultBranch?: string): Promise<void>;
-/** Write the incoming PACK into objects/pack/ and index it. */
-declare function indexIncomingPack(repo: Repo, packData: Uint8Array, hooks?: HttpHooks): Promise<string[]>;
-/**
- * Apply ref updates, enforcing compare-and-swap against each command's
- * claimed oldOid. Every client-supplied refName is validated before any
- * filesystem call reads or writes through it.
- */
-declare function applyRefUpdates(repo: Repo, refUpdates: RefUpdateCommand[], hooks?: HttpHooks): Promise<RefUpdateResult[]>;
-/** The report-status response body for a set of ref-update results. */
-declare function receivePackResponse(results: RefUpdateResult[]): GitHttpResult;
-interface ApplyReceivePackOptions {
-    defaultBranch?: string;
-    /**
-     * Repack tuning, or `false` to skip repacking entirely. The returned
-     * `stalePackPaths` are gitdir-relative pack files the repack deleted from
-     * this repo — after syncing to any secondary storage, delete them there
-     * too.
-     */
-    repack?: RepackOptions | false;
-}
-/**
- * The storage half of a push against `repo`: initialize if needed, index the
- * incoming pack, CAS-apply ref updates, then repack when enough packs have
- * accumulated. Serialize concurrent pushes to the same repo externally (a
- * per-repo lock); build the HTTP response afterwards with
- * {@link receivePackResponse}.
- */
-declare function applyReceivePack(repo: Repo, parsed: {
-    refUpdates: RefUpdateCommand[];
-    packData: Uint8Array;
-}, options?: ApplyReceivePackOptions, hooks?: HttpHooks): Promise<{
-    results: RefUpdateResult[];
-    stalePackPaths: string[];
-}>;
-
-interface UploadPackOptions {
-    /**
-     * Called once before the reachability walk — wire loose-object detection
-     * (`GitFs.detectLooseObjects`) here so a fully packed repo's walk doesn't
-     * pay a doomed loose-object probe per object.
-     */
-    beforeWalk?: () => Promise<void>;
-}
-/**
- * `POST …/git-upload-pack` — serve a clone/fetch. Authorization is the
- * caller's job. Negotiation is client-driven (no multi_ack advertised):
- * "have" batches without "done" get a bare NAK; the final batch gets the
- * packfile, side-band-64k framed.
- *
- * Fast path: a fresh clone (no haves) of a repo consolidated down to a
- * single pack serves that pack's bytes directly — skipping the O(objects)
- * traversal + repack entirely.
- */
-declare function handleUploadPack(repo: Repo, body: Uint8Array, options?: UploadPackOptions, hooks?: HttpHooks): Promise<GitHttpResult>;
-
-export { type ApplyReceivePackOptions, FLUSH, type GitHttpResult, type GitService, type HttpHooks, type InfoRefsOptions, REPACK_PACK_COUNT_THRESHOLD, type RawFsPromises, type ReachabilityResult, type RefUpdateCommand, type RefUpdateResult, type RepackOptions, type UploadPackOptions, applyReceivePack, applyRefUpdates, collectReachableOids, ensureRepoInitialized, handleInfoRefs, handleUploadPack, indexIncomingPack, listAllRefs, parsePktLines, parseReceivePackBody, pktLine, pktLineBuffer, rawFs, receivePackResponse, repackRepository, sideBandPackfile };