Reference — /http
Every export from git-fs-s3/http.
import { /* ... */ } from 'git-fs-s3/http';See the overview for HttpHooks and the
overall shape, and Serving clones and pushes
for a full worked example.
info/refs
handleInfoRefshandleInfoRefs(repo: Repo, options: InfoRefsOptions, hooks?: HttpHooks): Promise<GitHttpResult>| Parameter | Type | Description |
|---|---|---|
options.service | "git-upload-pack" | "git-receive-pack" | |
options.defaultBranch | string | Advertised as HEAD when HEAD itself doesn't name an existing branch. |
options.agent? | string | Advertised in the capability line. Default "git-fs-s3". |
Returns: Promise<GitHttpResult>
The GET .../info/refs?service=… ref advertisement. Authentication and
authorization are the caller's job before invoking this.
listAllRefslistAllRefs(repo: Repo, defaultBranch?: string): Promise<{ refs, headSymref }>Returns: Promise<{ refs: { name; oid }[]; headSymref: string }>
The lower-level primitive handleInfoRefs is built on, exposed in case
you need the raw ref list without the pkt-line framing.
upload-pack
handleUploadPackhandleUploadPack(repo: Repo, body: Uint8Array, options?: UploadPackOptions, hooks?: HttpHooks): Promise<GitHttpResult>| Parameter | Type | Description |
|---|---|---|
body | Uint8Array | The raw POST body. |
options.beforeWalk? | () => Promise<void> | Called once before the reachability walk — wire loose-object detection here. |
Returns: Promise<GitHttpResult>
Serves a clone/fetch. 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. A fresh clone of a repo
already consolidated to a single pack serves that pack's bytes directly,
skipping the reachability walk entirely.
receive-pack
parseReceivePackBodyparseReceivePackBody(body: Uint8Array): { refUpdates: RefUpdateCommand[]; packData: Uint8Array }Returns: { refUpdates: RefUpdateCommand[]; packData: Uint8Array }
Splits a receive-pack body into its pkt-line ref-update commands and the trailing raw pack bytes.
applyReceivePackapplyReceivePack(repo: Repo, parsed: ReturnType<typeof parseReceivePackBody>, options: ApplyReceivePackOptions, hooks?: HttpHooks): Promise<{ results, stalePackPaths }>| Parameter | Type | Description |
|---|---|---|
options.defaultBranch | string | HEAD's branch when a push initializes an empty repository. |
options.repack? | RepackOptions | false | Repack tuning, or false to skip repacking entirely. |
Returns: Promise<{ results: RefUpdateResult[]; stalePackPaths: string[] }>
The storage half of a push: initializes the repo if needed, indexes the
incoming pack, applies ref updates with compare-and-swap against each
command's claimed oldOid (a stale push is rejected, not force-applied),
then repacks once enough packs have accumulated. Build the HTTP response
afterwards with receivePackResponse. See
Repacking for stalePackPaths.
applyRefUpdatesapplyRefUpdates(repo: Repo, refUpdates: RefUpdateCommand[], hooks?: HttpHooks): Promise<RefUpdateResult[]>Returns: Promise<RefUpdateResult[]>
The ref-update half of applyReceivePack, exposed standalone. Every
client-supplied refName is validated with isSafeFullRefName before it
reaches any filesystem call — see the warning on
the overview page.
ensureRepoInitializedensureRepoInitialized(repo: Repo, defaultBranch?: string): Promise<void>Initializes the repo when HEAD doesn't exist yet (a first push).
indexIncomingPackindexIncomingPack(repo: Repo, packData: Uint8Array, hooks?: HttpHooks): Promise<void>Writes an incoming pack into objects/pack/ and indexes it.
receivePackResponsereceivePackResponse(results: RefUpdateResult[], options?: { capabilities?: string[]; unpackError?: string }): GitHttpResultReturns: GitHttpResult
Builds the report-status response from a set of ref-update results.
Pass the request's parsed capabilities: the report is side-band-64k
framed when the client asked for it (isomorphic-git's push always does,
and can't parse anything else), and empty when the client didn't ask for
report-status. unpackError (from applyReceivePack) reports a pack
that couldn't be stored, as unpack <error>.
Repacking
repackRepositoryrepackRepository(repo: Repo, options?: RepackOptions, hooks?: HttpHooks): Promise<string[]>Returns: Promise<string[]>
See the dedicated repacking page — the threshold, why every object is re-verified, and the deletion contract.
REPACK_PACK_COUNT_THRESHOLD (= 4) is the default RepackOptions.threshold.
Reachability
collectReachableOidscollectReachableOids(repo: Repo, startOids: string[], hooks?: HttpHooks, haveOids?: ReadonlySet<string> | readonly string[], options?: { verifyBlobs?: boolean }): Promise<ReachabilityResult>| Parameter | Type | Description |
|---|---|---|
startOids | string[] | The oids to walk from. |
hooks? | HttpHooks | See the overview page. |
haveOids? | ReadonlySet<string> | readonly string[] | Oids assumed already present: they are recorded without being read or descended into. Bounds a fetch to the new objects. |
options.verifyBlobs? | boolean | Read blobs too (default true). Set false when the caller reads every blob itself afterwards. |
Returns: Promise<ReachabilityResult>
Walks the full object graph from startOids. { oids, complete } —
complete: false if any object in the graph couldn't be read; a missing
object is retried once (a read landing mid-repack-transition can
transiently miss an object that isn't actually lost) before being
reported through hooks.onWarn. In-flight object reads are bounded by one
semaphore per walk (MAX_CONCURRENT_READS).
pkt-line framing
Low-level helpers, exposed if you're implementing protocol pieces this module doesn't cover:
| Export | Signature |
|---|---|
FLUSH | Uint8Array — the flush-pkt ("0000"). |
pktLine | (data: string) => Uint8Array |
pktLineBuffer | (body: Uint8Array) => Uint8Array |
parsePktLines | (buf: Uint8Array) => Array<string | null> — null marks a flush-pkt. |
sideBandPackfile | (packData: Uint8Array) => Uint8Array — chunks packfile bytes into side-band-64k framed pkt-lines. |
sideBandPackfile exists because clients that unconditionally expect
side-band framing on the response (isomorphic-git's own GitSideBand.demux
is one) misparse a raw packfile stream as bogus pkt-line length headers
and hang — this is required once side-band-64k is advertised, which
handleInfoRefs always does.
Types
| Export | Shape |
|---|---|
GitHttpResult | { status: number; headers: Record<string, string>; body: Uint8Array<ArrayBuffer> } |
HttpHooks | { step?, onWarn? } — see the overview. |
RawFsPromises | The .promises surface applyReceivePack/repackRepository need beyond isomorphic-git's own plumbing. |
rawFs | (repo: Repo) => RawFsPromises — duck-types the .promises surface off a repo's fs. |