nano-git 0.1.0

package/dist/transport/server/receive-pack/unpack.mjs

@@ -0,0 +1,119 @@
+import { sha1 } from "../../../core/types.mjs";
+import { hashObject } from "../../../core/hash-digest.mjs";
+import { numberToObjectType } from "../../../pack/constants.mjs";
+import { decodeObjectHeader } from "../../../pack/object-header.mjs";
+import { decodeOfsDeltaOffset } from "../../../pack/ofs-delta-offset.mjs";
+import { applyDelta } from "../../../pack/delta-apply.mjs";
+import { parsePackHeader, readCompressedData } from "../../../pack/pack-reader-utils.mjs";
+import { ReceivePackServiceError } from "./types.mjs";
+//#region src/transport/server/receive-pack/unpack.ts
+/**
+* Push packfile 解包（raw-first）
+*
+* 将 receive-pack push 请求中的 packfile 解包，
+* 将对象以 RawGitObject 形式摄入对象数据库，处理 ofs_delta 和 ref_delta。
+*
+* 所有对象按 canonical raw object 直接写入，不经过语义序列化/反序列化。
+*/
+/**
+* 将 push packfile 中的对象解包到对象数据库中
+*
+* 处理非 delta、ofs_delta 和 ref_delta 三种对象类型。
+* 对于 ref_delta，如果 base 不在当前 packfile 中，则从已存在的数据库查找。
+* 所有对象通过 db.ingest() 以 RawGitObject 形式直接写入。
+*
+* @param db - 对象数据库
+* @param packfile - push 请求中的 packfile 数据
+* @throws {ReceivePackServiceError} 当解包失败时
+*/
+function unpackPackfile(db, packfile) {
+	if (packfile.length < 32) throw new ReceivePackServiceError("Packfile too small to contain any objects");
+	const objectCount = parsePackHeader(packfile);
+	if (objectCount === 0) return;
+	const resolvedByOffset = /* @__PURE__ */ new Map();
+	const resolvedByHash = /* @__PURE__ */ new Map();
+	let offset = 12;
+	for (let i = 0; i < objectCount; i++) {
+		const objOffset = offset;
+		const [typeNum, , headerBytes] = decodeObjectHeader(packfile, offset);
+		offset += headerBytes;
+		if (typeNum === 6) {
+			const [negOffset, offsetBytes] = decodeOfsDeltaOffset(packfile, offset);
+			offset += offsetBytes;
+			const [deltaData, compressedBytes] = readCompressedData(packfile, offset);
+			offset += compressedBytes;
+			const baseOffset = objOffset - negOffset;
+			const base = resolvedByOffset.get(baseOffset);
+			if (!base) throw new ReceivePackServiceError(`ofs_delta base not found at offset ${baseOffset}`);
+			const resolvedData = applyDelta(base.data, deltaData);
+			const hash = hashObject(base.type, resolvedData);
+			const raw = {
+				hash,
+				type: base.type,
+				content: resolvedData
+			};
+			db.ingest(raw);
+			resolvedByOffset.set(objOffset, {
+				type: base.type,
+				data: resolvedData
+			});
+			resolvedByHash.set(hash, {
+				type: base.type,
+				data: resolvedData
+			});
+		} else if (typeNum === 7) {
+			const baseHash = packfile.subarray(offset, offset + 20).toString("hex");
+			offset += 20;
+			const [deltaData, compressedBytes] = readCompressedData(packfile, offset);
+			offset += compressedBytes;
+			let base;
+			const cachedBase = resolvedByHash.get(baseHash);
+			if (cachedBase) base = cachedBase;
+			else if (db.exists(sha1(baseHash))) {
+				const raw = db.read(sha1(baseHash));
+				base = {
+					type: raw.type,
+					data: raw.content
+				};
+			}
+			if (!base) throw new ReceivePackServiceError(`ref_delta base not found: ${baseHash}`);
+			const resolvedData = applyDelta(base.data, deltaData);
+			const resolvedHash = hashObject(base.type, resolvedData);
+			const raw = {
+				hash: resolvedHash,
+				type: base.type,
+				content: resolvedData
+			};
+			db.ingest(raw);
+			resolvedByOffset.set(objOffset, {
+				type: base.type,
+				data: resolvedData
+			});
+			resolvedByHash.set(resolvedHash, {
+				type: base.type,
+				data: resolvedData
+			});
+		} else {
+			const [compressedData, compressedBytes] = readCompressedData(packfile, offset);
+			offset += compressedBytes;
+			const type = numberToObjectType(typeNum);
+			const hash = hashObject(type, compressedData);
+			const raw = {
+				hash,
+				type,
+				content: compressedData
+			};
+			db.ingest(raw);
+			resolvedByOffset.set(objOffset, {
+				type,
+				data: compressedData
+			});
+			resolvedByHash.set(hash, {
+				type,
+				data: compressedData
+			});
+		}
+	}
+}
+//#endregion
+export { unpackPackfile };

package/dist/transport/server/upload-pack/advertise.d.mts

@@ -0,0 +1,20 @@
+//#region src/transport/server/upload-pack/advertise.d.ts
+/**
+ * upload-pack 能力广告生成
+ *
+ * 生成 upload-pack 的 v2 能力广告。
+ */
+/**
+ * 生成 v2 能力广告
+ *
+ * @returns 完整的 pkt-line 编码能力广告
+ *
+ * @example
+ * ```ts
+ * const response = advertiseUploadPack();
+ * // "000eversion 2\n000bls-refs\n...0000"
+ * ```
+ */
+declare function advertiseUploadPack(): Buffer;
+//#endregion
+export { advertiseUploadPack };

package/dist/transport/server/upload-pack/advertise.mjs

@@ -0,0 +1,30 @@
+import { encodeFlushPkt, encodePktLine } from "../../protocol/pkt-line.mjs";
+import { SERVER_AGENT } from "./types.mjs";
+//#region src/transport/server/upload-pack/advertise.ts
+/**
+* upload-pack 能力广告生成
+*
+* 生成 upload-pack 的 v2 能力广告。
+*/
+/**
+* 生成 v2 能力广告
+*
+* @returns 完整的 pkt-line 编码能力广告
+*
+* @example
+* ```ts
+* const response = advertiseUploadPack();
+* // "000eversion 2\n000bls-refs\n...0000"
+* ```
+*/
+function advertiseUploadPack() {
+	const parts = [];
+	parts.push(encodePktLine("version 2\n"));
+	parts.push(encodePktLine("ls-refs\n"));
+	parts.push(encodePktLine("fetch=shallow ref-in-want filter\n"));
+	parts.push(encodePktLine(`agent=${SERVER_AGENT}\n`));
+	parts.push(encodeFlushPkt());
+	return Buffer.concat(parts);
+}
+//#endregion
+export { advertiseUploadPack };

package/dist/transport/server/upload-pack/command.d.mts

@@ -0,0 +1,43 @@
+//#region src/transport/server/upload-pack/command.d.ts
+/**
+ * v2 命令请求解析
+ *
+ * 解析 v2 协议中 command/capability/args 三段式请求体。
+ *
+ * 请求格式：
+ * ```
+ * command=<name>\n
+ * <capability-list>
+ * 0001
+ * <command-args>
+ * 0000
+ * ```
+ *
+ * @see https://git-scm.com/docs/protocol-v2#_request
+ */
+/**
+ * 解析后的命令请求
+ */
+interface ParsedCommandRequest {
+  /** 命令名称（如 "ls-refs"、"fetch"） */
+  readonly command: string;
+  /** capability-list（command 行后的 pkt-line，至 delimiter 前） */
+  readonly capabilities: string[];
+  /** command-args（delimiter 后的 pkt-line，至 flush 前） */
+  readonly args: string[];
+}
+/**
+ * 解析 v2 命令请求体
+ *
+ * @param body - 完整的请求体（pkt-line 编码）
+ * @returns 解析后的命令信息
+ *
+ * @example
+ * ```ts
+ * const cmd = parseCommandRequest(body);
+ * console.log(cmd.command); // "ls-refs"
+ * ```
+ */
+declare function parseCommandRequest(body: Buffer): ParsedCommandRequest;
+//#endregion
+export { ParsedCommandRequest, parseCommandRequest };

package/dist/transport/server/upload-pack/command.mjs

@@ -0,0 +1,56 @@
+import { parsePktLines } from "../../protocol/pkt-line.mjs";
+//#region src/transport/server/upload-pack/command.ts
+/**
+* v2 命令请求解析
+*
+* 解析 v2 协议中 command/capability/args 三段式请求体。
+*
+* 请求格式：
+* ```
+* command=<name>\n
+* <capability-list>
+* 0001
+* <command-args>
+* 0000
+* ```
+*
+* @see https://git-scm.com/docs/protocol-v2#_request
+*/
+/**
+* 解析 v2 命令请求体
+*
+* @param body - 完整的请求体（pkt-line 编码）
+* @returns 解析后的命令信息
+*
+* @example
+* ```ts
+* const cmd = parseCommandRequest(body);
+* console.log(cmd.command); // "ls-refs"
+* ```
+*/
+function parseCommandRequest(body) {
+	const pktLines = parsePktLines(body);
+	let command = "";
+	const capabilities = [];
+	const args = [];
+	let afterDelimiter = false;
+	for (const pkt of pktLines) {
+		if (pkt.type === "flush") break;
+		if (pkt.type === "delimiter") {
+			afterDelimiter = true;
+			continue;
+		}
+		if (pkt.type !== "data") continue;
+		const text = pkt.payload.toString("utf-8").replace(/\n$/, "");
+		if (!afterDelimiter) if (text.startsWith("command=")) command = text.slice(8);
+		else capabilities.push(text);
+		else args.push(text);
+	}
+	return {
+		command,
+		capabilities,
+		args
+	};
+}
+//#endregion
+export { parseCommandRequest };

package/dist/transport/server/upload-pack/fetch.d.mts

@@ -0,0 +1,43 @@
+import { SHA1 } from "../../../core/types.mjs";
+import { RepositoryBackend } from "../../../backend/types.mjs";
+
+//#region src/transport/server/upload-pack/fetch.d.ts
+/** 从 fetch 请求 args 中解析的参数 */
+interface FetchServerParams {
+  readonly wants: SHA1[];
+  readonly haves: SHA1[];
+  readonly wantRefs: string[];
+  readonly done: boolean;
+  readonly thinPack: boolean;
+  readonly noProgress: boolean;
+  readonly ofsDelta: boolean;
+}
+/**
+ * 从 args 中解析 fetch 参数
+ *
+ * @param args - fetch 命令的 args 列表
+ * @returns 结构化的 fetch 参数
+ *
+ * @example
+ * ```ts
+ * const params = parseFetchArgs(["want <oid>", "have <oid>", "done"]);
+ * // { wants: [<oid>], haves: [<oid>], done: true, ... }
+ * ```
+ */
+declare function parseFetchArgs(args: string[]): FetchServerParams;
+/**
+ * 生成 v2 fetch 响应
+ *
+ * @param backend - 仓库后端
+ * @param params - 解析后的 fetch 参数
+ * @returns 完整的 v2 fetch 响应（pkt-line 编码）
+ *
+ * @example
+ * ```ts
+ * const params = parseFetchArgs(["want <oid>", "done"]);
+ * const response = generateFetchResponse(backend, params);
+ * ```
+ */
+declare function generateFetchResponse(backend: RepositoryBackend, params: FetchServerParams): Buffer;
+//#endregion
+export { FetchServerParams, generateFetchResponse, parseFetchArgs };

package/dist/transport/server/upload-pack/fetch.mjs

@@ -0,0 +1,217 @@
+import { sha1 } from "../../../core/types.mjs";
+import { resolveRefHash } from "../../../refs/resolve.mjs";
+import { encodeDelimiterPkt, encodeFlushPkt, encodePktLine } from "../../protocol/pkt-line.mjs";
+import { collectReachable } from "../../protocol/object-graph.mjs";
+import { createPackWriter } from "../../../pack/pack-writer.mjs";
+import { MAX_PKT_PAYLOAD, UploadPackServiceError } from "./types.mjs";
+//#region src/transport/server/upload-pack/fetch.ts
+/**
+* v2 fetch 命令响应生成
+*
+* 处理 fetch 命令，计算对象集合、构建 packfile、生成 fetch 响应。
+*
+* @see https://git-scm.com/docs/protocol-v2#_fetch
+*/
+/**
+* 从 args 中解析 fetch 参数
+*
+* @param args - fetch 命令的 args 列表
+* @returns 结构化的 fetch 参数
+*
+* @example
+* ```ts
+* const params = parseFetchArgs(["want <oid>", "have <oid>", "done"]);
+* // { wants: [<oid>], haves: [<oid>], done: true, ... }
+* ```
+*/
+function parseFetchArgs(args) {
+	const wants = [];
+	const haves = [];
+	const wantRefs = [];
+	let done = false;
+	let thinPack = false;
+	let noProgress = false;
+	let ofsDelta = false;
+	for (const arg of args) if (arg === "done") done = true;
+	else if (arg === "thin-pack") thinPack = true;
+	else if (arg === "no-progress") noProgress = true;
+	else if (arg === "ofs-delta") ofsDelta = true;
+	else if (arg.startsWith("want ")) wants.push(sha1(arg.slice(5).trim()));
+	else if (arg.startsWith("have ")) haves.push(sha1(arg.slice(5).trim()));
+	else if (arg.startsWith("want-ref ")) wantRefs.push(arg.slice(9).trim());
+	return {
+		wants,
+		haves,
+		wantRefs,
+		done,
+		thinPack,
+		noProgress,
+		ofsDelta
+	};
+}
+/**
+* 计算要打包的对象集合
+*
+* - 无 haves（clone）：返回所有 want 对象及其可达对象
+* - 有 haves（增量 fetch）：返回 want 可达对象与 have 可达对象的差集
+*/
+function computeObjectsToPack(backend, params) {
+	if (params.haves.length === 0) return collectReachable(backend.objects, params.wants, "skip-commit-parents");
+	const wantReachable = collectReachable(backend.objects, params.wants, "skip-commit-parents");
+	const haveReachable = collectReachable(backend.objects, params.haves, "skip-commit-parents");
+	const result = /* @__PURE__ */ new Set();
+	for (const hash of wantReachable) if (!haveReachable.has(hash)) result.add(hash);
+	return result;
+}
+/**
+* 将 packfile 数据以 side-band channel 1 格式分帧
+*
+* 每个 pkt-line 帧：<4字节长度><1字节channel><数据>
+*/
+function encodePackfileWithSideBand(packfile) {
+	const maxPayload = MAX_PKT_PAYLOAD - 1;
+	const frames = [];
+	let offset = 0;
+	while (offset < packfile.length) {
+		const chunkSize = Math.min(maxPayload, packfile.length - offset);
+		const frame = Buffer.alloc(1 + chunkSize);
+		frame[0] = 1;
+		packfile.copy(frame, 1, offset, offset + chunkSize);
+		frames.push(encodePktLine(frame));
+		offset += chunkSize;
+	}
+	return frames;
+}
+/**
+* 生成带 packfile 的 fetch 响应
+*
+* 响应结构遵循 protocol-v2（节之间以 delim-pkt 分隔，最后以 flush-pkt 收尾）：
+* ```
+* [acknowledgments\n ACK...\n ready\n 0001]    ← 仅协商命中 ready 时（无 done）
+* [wanted-refs\n <oid> <refname>\n ... 0001]   ← 仅当客户端使用 want-ref
+* packfile\n
+* <side-band 编码的 packfile 数据>
+* 0000
+* ```
+*
+* 注意：
+* - 当请求带 `done`（无 acknowledgments 节）时，section 不应以 delim-pkt 开头——
+*   首节直接是 wanted-refs 或 packfile。早期实现错误地在 packfile 前加了 leading
+*   delim-pkt，导致 git CLI 报 `fatal: expected 'packfile'`。
+* - 当协商阶段（无 done）服务端判定 ready 时，必须在 **同一响应** 中
+*   acknowledgments 节之后紧接 packfile，否则 git 报
+*   `fatal: expected packfile after 'ready'`。
+*
+* @param wantedRefs - want-ref 解析出的 refname→oid 映射（无则不发 wanted-refs 节）
+* @param ackSection - 可选的 acknowledgments 节内容（不含分隔 delim）；提供时会在其后补一个 delim-pkt
+*/
+function generatePackfileResponse(backend, params, wantedRefs, ackSection) {
+	const parts = [];
+	if (ackSection !== void 0) {
+		parts.push(ackSection);
+		parts.push(encodeDelimiterPkt());
+	}
+	if (wantedRefs.length > 0) {
+		parts.push(encodePktLine("wanted-refs\n"));
+		for (const { refname, oid } of wantedRefs) parts.push(encodePktLine(`${oid} ${refname}\n`));
+		parts.push(encodeDelimiterPkt());
+	}
+	const toPack = computeObjectsToPack(backend, params);
+	const writer = createPackWriter();
+	for (const hash of toPack) {
+		const raw = backend.objects.tryRead(hash);
+		if (raw) writer.addRaw(raw);
+	}
+	const packfile = writer.build();
+	parts.push(encodePktLine("packfile\n"));
+	if (packfile.length > 0) parts.push(...encodePackfileWithSideBand(packfile));
+	parts.push(encodeFlushPkt());
+	return Buffer.concat(parts);
+}
+/**
+* 查找 wants 与 haves 间的共同对象
+*
+* 当前简化实现：返回所有在本地仓库中存在且出现在 haves 中的哈希。
+* 更完善的实现应通过 commit 图 BFS 验证祖先关系。
+*/
+function findCommonObjects(backend, _wants, haves) {
+	const common = [];
+	for (const have of haves) if (backend.objects.exists(have)) common.push(have);
+	return {
+		common,
+		ready: common.length > 0
+	};
+}
+/**
+* 构建 acknowledgments 节内容（不含尾部 flush/delim）
+*
+* ```
+* acknowledgments\n
+* NAK\n
+* --- 或 ---
+* acknowledgments\n
+* ACK <oid>\n
+* ready\n
+* ```
+*
+* @returns section 内容及是否 ready
+*/
+function buildAcknowledgmentsSection(backend, params) {
+	const parts = [];
+	parts.push(encodePktLine("acknowledgments\n"));
+	const { common, ready } = findCommonObjects(backend, params.wants, params.haves);
+	if (common.length > 0) {
+		for (const oid of common) parts.push(encodePktLine(`ACK ${oid}\n`));
+		if (ready) parts.push(encodePktLine("ready\n"));
+	} else parts.push(encodePktLine("NAK\n"));
+	return {
+		section: Buffer.concat(parts),
+		ready
+	};
+}
+/**
+* 生成 v2 fetch 响应
+*
+* @param backend - 仓库后端
+* @param params - 解析后的 fetch 参数
+* @returns 完整的 v2 fetch 响应（pkt-line 编码）
+*
+* @example
+* ```ts
+* const params = parseFetchArgs(["want <oid>", "done"]);
+* const response = generateFetchResponse(backend, params);
+* ```
+*/
+function generateFetchResponse(backend, params) {
+	if (params.wants.length === 0 && params.wantRefs.length === 0) throw new UploadPackServiceError("fetch: no wants or want-refs specified");
+	for (const want of params.wants) if (!backend.objects.exists(want)) {
+		const parts = [];
+		parts.push(encodePktLine("packfile\n"));
+		parts.push(encodePktLine(Buffer.concat([Buffer.from([3]), Buffer.from(`want ${want} not found\n`)])));
+		parts.push(encodeFlushPkt());
+		return Buffer.concat(parts);
+	}
+	const effectiveWants = [...params.wants];
+	const wantedRefs = [];
+	for (const ref of params.wantRefs) {
+		const hash = resolveRefHash(backend.refs, ref);
+		if (hash !== null) {
+			effectiveWants.push(hash);
+			wantedRefs.push({
+				refname: ref,
+				oid: hash
+			});
+		}
+	}
+	const effectiveParams = {
+		...params,
+		wants: effectiveWants
+	};
+	if (effectiveParams.wants.length === 0) throw new UploadPackServiceError("fetch: no wants resolved");
+	if (params.done) return generatePackfileResponse(backend, effectiveParams, wantedRefs);
+	const { section: ackSection, ready } = buildAcknowledgmentsSection(backend, effectiveParams);
+	if (ready) return generatePackfileResponse(backend, effectiveParams, wantedRefs, ackSection);
+	return Buffer.concat([ackSection, encodeFlushPkt()]);
+}
+//#endregion
+export { generateFetchResponse, parseFetchArgs };

package/dist/transport/server/upload-pack/index.d.mts

@@ -0,0 +1,7 @@
+import { advertiseUploadPack } from "./advertise.mjs";
+import { ParsedCommandRequest, parseCommandRequest } from "./command.mjs";
+import { LsRefsServerOptions, generateLsRefsResponse, parseLsRefsArgs } from "./ls-refs.mjs";
+import { FetchServerParams, generateFetchResponse, parseFetchArgs } from "./fetch.mjs";
+import { UploadPackServiceError } from "./types.mjs";
+import { UploadPackService, createUploadPackService } from "./service.mjs";
+export { type FetchServerParams, type LsRefsServerOptions, type ParsedCommandRequest, type UploadPackService, UploadPackServiceError, advertiseUploadPack, createUploadPackService, generateFetchResponse, generateLsRefsResponse, parseCommandRequest, parseFetchArgs, parseLsRefsArgs };

package/dist/transport/server/upload-pack/index.mjs

@@ -0,0 +1,7 @@
+import { UploadPackServiceError } from "./types.mjs";
+import { advertiseUploadPack } from "./advertise.mjs";
+import { parseCommandRequest } from "./command.mjs";
+import { generateLsRefsResponse, parseLsRefsArgs } from "./ls-refs.mjs";
+import { generateFetchResponse, parseFetchArgs } from "./fetch.mjs";
+import { createUploadPackService } from "./service.mjs";
+export { UploadPackServiceError, advertiseUploadPack, createUploadPackService, generateFetchResponse, generateLsRefsResponse, parseCommandRequest, parseFetchArgs, parseLsRefsArgs };

package/dist/transport/server/upload-pack/ls-refs.d.mts

@@ -0,0 +1,38 @@
+import { RepositoryBackend } from "../../../backend/types.mjs";
+
+//#region src/transport/server/upload-pack/ls-refs.d.ts
+/** ls-refs 请求中解析出的选项 */
+interface LsRefsServerOptions {
+  readonly symrefs: boolean;
+  readonly peel: boolean;
+  readonly unborn: boolean;
+  readonly refPrefixes: string[];
+}
+/**
+ * 从 args 中解析 ls-refs 选项
+ *
+ * @param args - ls-refs 命令的 args 列表
+ * @returns 结构化的 ls-refs 选项
+ *
+ * @example
+ * ```ts
+ * const opts = parseLsRefsArgs(["symrefs", "peel", "ref-prefix refs/heads/"]);
+ * // { symrefs: true, peel: true, unborn: false, refPrefixes: ["refs/heads/"] }
+ * ```
+ */
+declare function parseLsRefsArgs(args: string[]): LsRefsServerOptions;
+/**
+ * 生成 ls-refs 响应
+ *
+ * @param backend - 仓库后端
+ * @param options - ls-refs 选项
+ * @returns pkt-line 编码的 ls-refs 响应
+ *
+ * @example
+ * ```ts
+ * const buf = generateLsRefsResponse(backend, { symrefs: true, peel: true, unborn: false, refPrefixes: [] });
+ * ```
+ */
+declare function generateLsRefsResponse(backend: RepositoryBackend, options: LsRefsServerOptions): Buffer;
+//#endregion
+export { LsRefsServerOptions, generateLsRefsResponse, parseLsRefsArgs };