@skydiveai/git-cache 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Create, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { f as startServer } from "./server-B5u5DETT.mjs";
+//#region src/cli.ts
+/**
+* `git-cache` CLI — the published binary for @skydiveai/git-cache.
+*
+* Subcommands:
+*   serve    start the loopback cache daemon (the long-running process the
+*            sandbox launches at boot via supervisord). Config comes from env
+*            (GIT_CACHE_PORT, GIT_CACHE_DIR, GIT_CACHE_CREDENTIAL_HELPER, …).
+*   version  print the package version.
+*
+* The in-sandbox on/off wiring (git-config rewrites, opt-out, daemon start/stop)
+* lives in the thin shell layer that ships with the sandbox image
+* (git-cache-apply.sh / git-cache-ctl.sh); this binary is the daemon itself.
+*/
+async function main() {
+	const cmd = process.argv[2] ?? "serve";
+	switch (cmd) {
+		case "serve":
+			await startServer();
+			return;
+		case "version":
+		case "--version":
+		case "-v":
+			process.stdout.write(`${process.env.npm_package_version ?? "unknown"}\n`);
+			return;
+		case "help":
+		case "--help":
+		case "-h":
+			process.stdout.write("usage: git-cache-daemon <serve|version>\n  serve    start the loopback git cache daemon (default)\n  version  print the daemon version\n");
+			return;
+		default:
+			process.stderr.write(`git-cache: unknown command '${cmd}'\n`);
+			process.exit(2);
+	}
+}
+main().catch((error) => {
+	process.stderr.write(`git-cache: fatal: ${String(error)}\n`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,179 @@
+import * as _$node_stream0 from "node:stream";
+
+//#region src/server.d.ts
+/** The counter payload `/metrics` serves. Copied so callers can't mutate it. */
+declare function metricsSnapshot(): {
+  cold_requests: number;
+  cold_followers: number;
+  warm_hits: number;
+  refreshes: number;
+  publications: number;
+  abandoned_ineligible: number;
+  abandoned_oversize: number;
+  abandoned_queue_overflow: number;
+  abandoned_import_error: number;
+  abandoned_disconnect: number;
+  passthrough_ineligible: number;
+  passthrough_missing_want: number;
+  invalidations: number;
+  evictions: number;
+  refresh_failures: number;
+  refresh_deferred: number;
+  publish_deferred: number;
+  credential_url_redirects: number;
+  lfs_redirects: number;
+  upstream_errors: number;
+  bad_requests: number;
+  cold_proxy_bytes: number;
+  captured_pack_bytes: number;
+  cold_build_failures: number;
+  backfills: number;
+  backfill_failures: number;
+  auth_checks: number;
+  auth_memo_hits: number;
+  auth_denials: number;
+};
+/**
+ * Record the outcome of a finished cold build. A failure leaves the mirror
+ * unpublished, so every later clone silently pays full upstream cost — it must
+ * move a counter and not just write a log line, or a cache that never publishes
+ * reads as healthy on /metrics.
+ */
+declare function recordColdBuildOutcome(error: unknown): void;
+/** A ref line from a smart-HTTP advertisement (peeled tags excluded). */
+type AdvertisedRef = {
+  oid: string;
+  ref: string;
+};
+/** Parsed `info/refs` advertisement: the fetchable refs + object-format flag. */
+type Advertisement = {
+  refs: AdvertisedRef[];
+  sha256: boolean;
+};
+/**
+ * Guard against non-numeric env values explicitly: NaN would only be
+ * fail-safe through the accident of `elapsed < NaN` being false, and any
+ * later refactor to a `>= ttl` comparison would silently flip that into
+ * memoize-forever.
+ */
+/**
+ * Turn a rewritten cache path into a validated upstream identity, or null.
+ * The first path segment is the authority (host or host:port); the rest is the
+ * repo path. We reject anything that isn't a plain public https git host.
+ */
+/** parseUpstream result: either a validated upstream identity to serve, or a
+ * redirect bouncing not-ours traffic (creds-in-URL, LFS API) to its true
+ * upstream. Discriminated by `redirect` so callers narrow with one check. */
+type ParsedUpstream = {
+  redirect?: undefined;
+  repo: string;
+  upstreamUrl: string;
+  operation: string;
+} | {
+  redirect: string;
+  operation: string;
+};
+declare function parseUpstream(rawPathname: any, rawSearch?: string): ParsedUpstream | null;
+/**
+ * Best-effort human explanation for a request parseUpstream refused, used
+ * ONLY in the 404 body so an agent whose (legitimate but unproxyable) remote
+ * hits a security rejection gets an actionable error instead of an opaque
+ * "git cache endpoint". Diagnostic only — the actual gate is parseUpstream;
+ * this never influences serving decisions, so a miss here is harmless.
+ */
+declare function explainRejection(rawPathname: string): string | null;
+/**
+ * Run `fn` while holding a named lock for `repo`, or return `null` without
+ * running it if another writer holds that lock.
+ *
+ * The in-memory guards elsewhere in this file (`inflightRefresh`,
+ * `coldLeaders`, `backfilling`) only serialize writers inside ONE process,
+ * which is the whole story when each process owns its own disk. On a mirror
+ * store shared between tasks they are blind to each other, so two tasks will
+ * happily fetch into, publish over, or evict the same mirror at the same
+ * time. This lock is what makes those operations mutually exclusive across
+ * every writer of the store.
+ *
+ * `mkdir` is the primitive because its create-or-fail is atomic on a single
+ * disk and over NFS alike. A lock whose mtime has stopped advancing is
+ * assumed abandoned and broken, so a task that dies mid-operation cannot
+ * wedge a repo forever.
+ */
+declare function copyRequestHeaders(headers: any): {};
+declare function parseAdvertisement(buffer: Buffer): Advertisement;
+/**
+ * Inspect a client's git-upload-pack request body to decide cache eligibility.
+ * We only ingest packs that can form a COMPLETE standalone mirror: no filter,
+ * no shallow/deepen, and no client-provided `have` lines (which would make the
+ * server omit objects the client already had). Everything else is passed
+ * through with ingestion disabled — correctness over coverage.
+ *
+ * Returns { eligible, reason }.
+ */
+/**
+ * True when a `git-upload-pack` POST body speaks protocol v2.
+ *
+ * v2 replaces v0's bare want/have lines with a leading `command=<verb>` line,
+ * so the first pkt-line identifies the dialect unambiguously.
+ */
+declare function isProtocolV2Request(buffer: any): boolean;
+declare function classifyUploadRequest(buffer: any): {
+  eligible: boolean;
+  reason: string;
+  wants: string[];
+};
+declare class SidebandPackExtractor {
+  writable: _$node_stream0.Writable;
+  buffer: Buffer;
+  sawPack: boolean;
+  inPackSection: boolean;
+  needsDrain: boolean;
+  errored: boolean;
+  constructor(writable: _$node_stream0.Writable);
+  push(chunk: any): boolean | undefined;
+  drained(): void;
+  end(): void;
+}
+/**
+ * Whether a request that could NOT be cached is worth building a mirror for
+ * out-of-band. Only uncacheable requests need it — a cacheable one already
+ * populated the cache — and a sha256 repo is excluded because the
+ * advertisement parser cannot read its 64-hex OIDs, so no correct mirror can
+ * be completed for it at all.
+ */
+declare function shouldBackfillAfterPassthrough({
+  cacheable,
+  sha256
+}: {
+  cacheable: any;
+  sha256: any;
+}): boolean;
+/**
+ * True when every OID is already present in the mirror.
+ *
+ * `git-upload-pack` refuses the whole request with `not our ref <oid>` if a
+ * single wanted object is missing, so this is the difference between serving
+ * a fetch and failing it. A mirror can legitimately lack a wanted object: the
+ * client negotiated against a fresher advertisement — from a sibling task
+ * holding its own mirror set, or from the sandbox-local cache tier — and asks
+ * for a commit this mirror has not fetched yet.
+ */
+declare function mirrorHasObjects(local: any, oids: string[]): Promise<boolean>;
+/**
+ * Explicit configuration overrides for startServer. Takes precedence over the
+ * environment snapshot taken at module load, so embedders (the shared service
+ * wrapper) configure the engine through this API instead of mutating
+ * process.env before import — an ordering contract that import hoisting made
+ * easy to violate silently.
+ */
+type StartServerOptions = {
+  authMode?: 'trusted-client' | 'check-through';
+  bindHost?: string;
+  port?: number;
+  cacheDir?: string;
+  maxCacheBytes?: number;
+  credentialHelper?: string;
+};
+declare function startServer(options?: StartServerOptions): Promise<void>;
+//#endregion
+export { SidebandPackExtractor, classifyUploadRequest, copyRequestHeaders, explainRejection, isProtocolV2Request, metricsSnapshot, mirrorHasObjects, parseAdvertisement, parseUpstream, recordColdBuildOutcome, shouldBackfillAfterPassthrough, startServer };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as isProtocolV2Request, c as parseAdvertisement, d as shouldBackfillAfterPassthrough, f as startServer, i as explainRejection, l as parseUpstream, n as classifyUploadRequest, o as metricsSnapshot, r as copyRequestHeaders, s as mirrorHasObjects, t as SidebandPackExtractor, u as recordColdBuildOutcome } from "./server-B5u5DETT.mjs";
+export { SidebandPackExtractor, classifyUploadRequest, copyRequestHeaders, explainRejection, isProtocolV2Request, metricsSnapshot, mirrorHasObjects, parseAdvertisement, parseUpstream, recordColdBuildOutcome, shouldBackfillAfterPassthrough, startServer };