nano-git 0.1.0

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

@@ -0,0 +1,88 @@
+import { sha1 } from "../../../core/types.mjs";
+import { tryReadObject } from "../../../objects/raw.mjs";
+import { resolveRefHash } from "../../../refs/resolve.mjs";
+import { encodeFlushPkt, encodePktLine } from "../../protocol/pkt-line.mjs";
+import { CAPABILITIES_REF, SERVER_AGENT, ZERO_HASH } from "./types.mjs";
+//#region src/transport/server/receive-pack/advertise.ts
+/**
+* receive-pack ref 广告生成
+*
+* 处理 GET /info/refs?service=git-receive-pack 请求，
+* 生成 v1 风格的 ref 广告（含 capabilities）。
+*
+* @see https://git-scm.com/docs/pack-protocol#_git_gt_transport
+*/
+/**
+* 读取仓库中的所有引用
+*/
+function readAllRefs(backend) {
+	const result = /* @__PURE__ */ new Map();
+	const headContent = backend.refs.read("HEAD");
+	if (headContent !== null) result.set("HEAD", headContent);
+	const refNames = backend.refs.listAll();
+	for (const ref of refNames) {
+		const content = backend.refs.read(ref);
+		if (content !== null) result.set(ref, content);
+	}
+	return result;
+}
+/**
+* 生成 receive-pack 的 ref 广告
+*
+* 格式：
+* ```
+* 001e# service=git-receive-pack\n
+* 0000
+* <length><hash> <refname>\0<capabilities>\n   ← 首行 ref 携带 capabilities
+* <length><hash> <refname>\n                    ← 后续 ref
+* ...
+* 0000
+* ```
+*
+* @param backend - 仓库后端
+* @returns 完整 advertisement（pkt-line 编码）
+*
+* @example
+* ```ts
+* const buf = advertiseReceivePack(backend);
+* // Response 的 Content-Type 应为 "application/x-git-receive-pack-advertisement"
+* ```
+*/
+function advertiseReceivePack(backend) {
+	const parts = [];
+	parts.push(encodePktLine("# service=git-receive-pack\n"));
+	parts.push(encodeFlushPkt());
+	const refs = readAllRefs(backend);
+	const capStr = [
+		"report-status",
+		"delete-refs",
+		"side-band-64k",
+		"ofs-delta",
+		"no-progress",
+		`agent=${SERVER_AGENT}`
+	].join(" ");
+	let firstRef = true;
+	for (const [refName, content] of refs) if (content.startsWith("ref: ")) {
+		const resolved = resolveRefHash(backend.refs, refName);
+		if (resolved === null) continue;
+		const line = firstRef ? `${resolved} ${refName}\0${capStr}\n` : `${resolved} ${refName}\n`;
+		parts.push(encodePktLine(line));
+		const target = content.slice(5);
+		parts.push(encodePktLine(`${resolved} ${refName} symref-target:${target}\n`));
+		firstRef = false;
+	} else if (/^[0-9a-f]{40}$/.test(content)) {
+		const hash = sha1(content);
+		const line = firstRef ? `${hash} ${refName}\0${capStr}\n` : `${hash} ${refName}\n`;
+		parts.push(encodePktLine(line));
+		if (refName.startsWith("refs/tags/")) {
+			const obj = tryReadObject(backend.objects, hash);
+			if (obj?.type === "tag") parts.push(encodePktLine(`${obj.object} ${refName}^{}\n`));
+		}
+		firstRef = false;
+	}
+	if (firstRef) parts.push(encodePktLine(`${ZERO_HASH} ${CAPABILITIES_REF}\0${capStr}\n`));
+	parts.push(encodeFlushPkt());
+	return Buffer.concat(parts);
+}
+//#endregion
+export { advertiseReceivePack };

package/dist/transport/server/receive-pack/handler.d.mts

@@ -0,0 +1,30 @@
+import { RepositoryBackend } from "../../../backend/types.mjs";
+import { ReceivePackOptions } from "./types.mjs";
+
+//#region src/transport/server/receive-pack/handler.d.ts
+/**
+ * 处理 receive-pack push 请求
+ *
+ * 完整流程：
+ * 1. 验证请求体非空
+ * 2. 解析客户端命令
+ * 3. 检查 delete-refs 能力（如需要删除）
+ * 4. 解包 packfile（如有）
+ * 5. 检查组删除 / 更新 / 创建条件
+ * 6. 批量应用 ref 更新
+ * 7. 返回 report-status
+ *
+ * @param backend - 仓库后端
+ * @param body - 完整的请求体
+ * @param options - 处理选项
+ * @returns report-status 响应（Buffer）
+ *
+ * @example
+ * ```ts
+ * const response = handleReceivePackRequest(backend, requestBody);
+ * // Response 的 Content-Type 应为 "application/x-git-receive-pack-result"
+ * ```
+ */
+declare function handleReceivePackRequest(backend: RepositoryBackend, body: Buffer, options?: ReceivePackOptions): Buffer;
+//#endregion
+export { handleReceivePackRequest };

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

@@ -0,0 +1,156 @@
+import { resolveRefHash } from "../../../refs/resolve.mjs";
+import { encodeFlushPkt } from "../../protocol/pkt-line.mjs";
+import { ReceivePackServiceError, ZERO_HASH } from "./types.mjs";
+import { parseReceivePackRequest } from "./parse.mjs";
+import { generateReceivePackReport } from "./report-status.mjs";
+import { unpackPackfile } from "./unpack.mjs";
+//#region src/transport/server/receive-pack/handler.ts
+/**
+* receive-pack 主处理函数
+*
+* 整合请求解析、packfile 解包、ref 校验与事务更新，
+* 生成 report-status 响应。
+*/
+/**
+* 校验单个 ref 更新命令的合法性
+*
+* 检查：
+* - oldHash 必须匹配 ref 当前值（新建时可为 000...0）
+* - newHash 对象必须存在
+* - 标签不可覆盖（允许 force — 但 v1 协议中 force 不在命令中体现）
+* - 删除操作需要 delete-refs 能力
+*/
+function checkRefUpdate(backend, cmd, _capabilities, _options) {
+	const { oldHash, newHash, refName } = cmd;
+	const isDelete = newHash === ZERO_HASH;
+	const isCreate = oldHash === ZERO_HASH;
+	const currentHash = resolveRefHash(backend.refs, refName);
+	if (isCreate) {
+		if (currentHash !== null) return {
+			ok: false,
+			error: `ref ${refName} already exists`
+		};
+		if (!backend.objects.exists(newHash)) return {
+			ok: false,
+			error: `object ${newHash} not found`
+		};
+		return { ok: true };
+	}
+	if (currentHash === null) return {
+		ok: false,
+		error: `ref ${refName} does not exist (expected ${oldHash})`
+	};
+	if (currentHash !== oldHash) return {
+		ok: false,
+		error: `ref ${refName} is at ${currentHash} but expected ${oldHash}`
+	};
+	if (isDelete) return { ok: true };
+	if (!backend.objects.exists(newHash)) return {
+		ok: false,
+		error: `object ${newHash} not found`
+	};
+	if (refName.startsWith("refs/tags/")) return {
+		ok: false,
+		error: `tag ${refName} already exists and cannot be overwritten without force`
+	};
+	return { ok: true };
+}
+/**
+* 在事务中应用批量 ref 更新
+*/
+function applyRefUpdates(backend, commands) {
+	const hooks = backend.refTransactionHooks;
+	const tx = backend.refs.beginTransaction(hooks);
+	try {
+		for (const cmd of commands) if (cmd.newHash === ZERO_HASH) tx.delete(cmd.refName);
+		else tx.write(cmd.refName, cmd.newHash);
+		tx.commit();
+	} catch (err) {
+		tx.rollback();
+		throw err;
+	}
+}
+/**
+* 处理 receive-pack push 请求
+*
+* 完整流程：
+* 1. 验证请求体非空
+* 2. 解析客户端命令
+* 3. 检查 delete-refs 能力（如需要删除）
+* 4. 解包 packfile（如有）
+* 5. 检查组删除 / 更新 / 创建条件
+* 6. 批量应用 ref 更新
+* 7. 返回 report-status
+*
+* @param backend - 仓库后端
+* @param body - 完整的请求体
+* @param options - 处理选项
+* @returns report-status 响应（Buffer）
+*
+* @example
+* ```ts
+* const response = handleReceivePackRequest(backend, requestBody);
+* // Response 的 Content-Type 应为 "application/x-git-receive-pack-result"
+* ```
+*/
+function handleReceivePackRequest(backend, body, options) {
+	let parsed;
+	try {
+		parsed = parseReceivePackRequest(body);
+	} catch (err) {
+		if (err instanceof ReceivePackServiceError) throw err;
+		throw new ReceivePackServiceError(`Failed to parse receive-pack request: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const { capabilities, commands, packfile } = parsed;
+	const hasReportStatus = capabilities.includes("report-status");
+	const hasSideBand = capabilities.includes("side-band-64k");
+	let unpackOk = true;
+	let unpackError;
+	if (packfile.length > 0) try {
+		unpackPackfile(backend.objects, packfile);
+	} catch (err) {
+		unpackOk = false;
+		unpackError = err instanceof Error ? err.message : String(err);
+	}
+	const successfulUpdates = [];
+	const refResults = [];
+	if (unpackOk) {
+		for (const cmd of commands) {
+			const check = checkRefUpdate(backend, cmd, capabilities, options);
+			if (check.ok) {
+				successfulUpdates.push({
+					refName: cmd.refName,
+					newHash: cmd.newHash
+				});
+				refResults.push({
+					refName: cmd.refName,
+					success: true
+				});
+			} else refResults.push({
+				refName: cmd.refName,
+				success: false,
+				error: check.error
+			});
+		}
+		if (successfulUpdates.length > 0) try {
+			applyRefUpdates(backend, successfulUpdates);
+		} catch (err) {
+			for (const up of successfulUpdates) {
+				const idx = refResults.findIndex((r) => r.refName === up.refName);
+				if (idx !== -1) refResults[idx] = {
+					refName: up.refName,
+					success: false,
+					error: `transaction failed: ${err instanceof Error ? err.message : String(err)}`
+				};
+			}
+		}
+	} else for (const cmd of commands) refResults.push({
+		refName: cmd.refName,
+		success: false,
+		error: "unpack error"
+	});
+	if (!hasReportStatus) return encodeFlushPkt();
+	return generateReceivePackReport(unpackOk, unpackError, refResults, hasSideBand);
+}
+//#endregion
+export { handleReceivePackRequest };

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

@@ -0,0 +1,6 @@
+import { advertiseReceivePack } from "./advertise.mjs";
+import { ParsedReceivePackRequest, ReceivePackCommand, ReceivePackOptions, ReceivePackServiceError, ReceivePackUpdateResult } from "./types.mjs";
+import { parseReceivePackRequest } from "./parse.mjs";
+import { handleReceivePackRequest } from "./handler.mjs";
+import { ReceivePackService, createReceivePackService } from "./service.mjs";
+export { type ParsedReceivePackRequest, type ReceivePackCommand, type ReceivePackOptions, type ReceivePackService, ReceivePackServiceError, type ReceivePackUpdateResult, advertiseReceivePack, createReceivePackService, handleReceivePackRequest, parseReceivePackRequest };

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

@@ -0,0 +1,6 @@
+import { ReceivePackServiceError } from "./types.mjs";
+import { advertiseReceivePack } from "./advertise.mjs";
+import { parseReceivePackRequest } from "./parse.mjs";
+import { handleReceivePackRequest } from "./handler.mjs";
+import { createReceivePackService } from "./service.mjs";
+export { ReceivePackServiceError, advertiseReceivePack, createReceivePackService, handleReceivePackRequest, parseReceivePackRequest };

package/dist/transport/server/receive-pack/parse.d.mts

@@ -0,0 +1,17 @@
+import { ParsedReceivePackRequest } from "./types.mjs";
+
+//#region src/transport/server/receive-pack/parse.d.ts
+/**
+ * 解析 receive-pack 请求 body
+ *
+ * @param body - 完整的请求 body
+ * @returns 解析后的命令、能力与 packfile
+ *
+ * @example
+ * ```ts
+ * const { commands, capabilities, packfile } = parseReceivePackRequest(body);
+ * ```
+ */
+declare function parseReceivePackRequest(body: Buffer): ParsedReceivePackRequest;
+//#endregion
+export { parseReceivePackRequest };

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

@@ -0,0 +1,80 @@
+import { sha1 } from "../../../core/types.mjs";
+import { splitPktLinesFromBuffer } from "../../protocol/pkt-line.mjs";
+import { ReceivePackServiceError } from "./types.mjs";
+//#region src/transport/server/receive-pack/parse.ts
+/**
+* receive-pack 请求解析
+*
+* 解析客户端 POST 的 ref 命令与 capabilities。
+*
+* 请求格式：
+* ```
+* <old-hash> <new-hash> <refname>\0<capabilities>\n   ← 首行
+* <old-hash> <new-hash> <refname>\n                    ← 后续行
+* ...
+* 0000                                                   ← flush
+* <packfile data>                                        ← packfile
+* ```
+*
+* @see https://git-scm.com/docs/pack-protocol#_git_gt_transport
+*/
+/**
+* 解析单行命令
+*
+* 格式：<old-hash> SP <new-hash> SP <refname>
+*/
+function parseCommandLine(text) {
+	const parts = text.split(" ");
+	if (parts.length < 3) return null;
+	const oldHash = parts[0];
+	const newHash = parts[1];
+	const refName = parts.slice(2).join(" ");
+	if (!/^[0-9a-f]{40}$/.test(oldHash)) return null;
+	if (!/^[0-9a-f]{40}$/.test(newHash)) return null;
+	return {
+		oldHash: sha1(oldHash),
+		newHash: sha1(newHash),
+		refName
+	};
+}
+/**
+* 解析 receive-pack 请求 body
+*
+* @param body - 完整的请求 body
+* @returns 解析后的命令、能力与 packfile
+*
+* @example
+* ```ts
+* const { commands, capabilities, packfile } = parseReceivePackRequest(body);
+* ```
+*/
+function parseReceivePackRequest(body) {
+	const { lines, trailing } = splitPktLinesFromBuffer(body);
+	const dataLines = lines.filter((l) => l.type === "data");
+	if (dataLines.length === 0) throw new ReceivePackServiceError("No commands in receive-pack request");
+	const commands = [];
+	let capabilities = [];
+	for (let i = 0; i < dataLines.length; i++) {
+		const text = dataLines[i].payload.toString("utf-8").replace(/\n$/, "");
+		if (i === 0) {
+			const nulIndex = text.indexOf("\0");
+			if (nulIndex !== -1) {
+				const cmdPart = text.substring(0, nulIndex);
+				capabilities = text.substring(nulIndex + 1).split(" ").filter(Boolean);
+				const cmd = parseCommandLine(cmdPart);
+				if (cmd) commands.push(cmd);
+				continue;
+			}
+		}
+		const cmd = parseCommandLine(text);
+		if (cmd) commands.push(cmd);
+	}
+	if (commands.length === 0) throw new ReceivePackServiceError("No valid ref update commands");
+	return {
+		capabilities,
+		commands,
+		packfile: trailing
+	};
+}
+//#endregion
+export { parseReceivePackRequest };

package/dist/transport/server/receive-pack/report-status.mjs

@@ -0,0 +1,64 @@
+import { encodeFlushPkt, encodePktLine } from "../../protocol/pkt-line.mjs";
+//#region src/transport/server/receive-pack/report-status.ts
+/**
+* receive-pack report-status 响应生成
+*
+* 生成 unpack 状态和 ref 更新结果的 pkt-line 编码响应。
+* 支持 side-band-64k 编码（progress 在 channel 2，report-status 在 channel 1）。
+*/
+/**
+* 编码 side-band 帧
+*/
+function encodeSideBandFrame(channel, data) {
+	const frame = Buffer.alloc(1 + data.length);
+	frame[0] = channel;
+	data.copy(frame, 1);
+	return encodePktLine(frame);
+}
+/**
+* 生成 receive-pack 的 report-status 响应
+*
+* 格式（无 side-band）：
+* ```
+* unpack <ok|error>\n
+* ok <refname>\n
+* ng <refname> <error>\n
+* ...
+* 0000
+* ```
+*
+* 格式（带 side-band-64k）：
+* ```
+* <side-band channel 2: progress>
+* <side-band channel 1: report-status lines>
+* 0000
+* ```
+*
+* @param unpackOk - 解包是否成功
+* @param unpackError - 解包错误消息（unpackOk 为 false 时）
+* @param refResults - 各 ref 的更新结果
+* @param useSideBand - 是否使用 side-band-64k 编码
+* @returns 完整的响应 Buffer
+*/
+function generateReceivePackReport(unpackOk, unpackError, refResults, useSideBand) {
+	const statusLines = [];
+	if (unpackOk) statusLines.push(Buffer.from("unpack ok\n", "utf-8"));
+	else statusLines.push(Buffer.from(`unpack ${unpackError ?? "unknown error"}\n`, "utf-8"));
+	for (const result of refResults) if (result.success) statusLines.push(Buffer.from(`ok ${result.refName}\n`, "utf-8"));
+	else statusLines.push(Buffer.from(`ng ${result.refName} ${result.error ?? "unknown error"}\n`, "utf-8"));
+	const reportStatusData = Buffer.concat(statusLines);
+	const pktParts = [];
+	const lines = reportStatusData.toString("utf-8").split("\n");
+	for (const line of lines) if (line.length > 0) pktParts.push(encodePktLine(line + "\n"));
+	pktParts.push(encodeFlushPkt());
+	const reportPktSequence = Buffer.concat(pktParts);
+	if (!useSideBand) return reportPktSequence;
+	const parts = [];
+	const progressMsg = `Unpacking objects: 100% (${refResults.length}/${refResults.length})\n`;
+	parts.push(encodeSideBandFrame(2, Buffer.from(progressMsg, "utf-8")));
+	parts.push(encodeSideBandFrame(1, reportPktSequence));
+	parts.push(encodeFlushPkt());
+	return Buffer.concat(parts);
+}
+//#endregion
+export { generateReceivePackReport };

package/dist/transport/server/receive-pack/service.d.mts

@@ -0,0 +1,41 @@
+import { RepositoryBackend } from "../../../backend/types.mjs";
+import { ReceivePackOptions } from "./types.mjs";
+
+//#region src/transport/server/receive-pack/service.d.ts
+/**
+ * Receive-Pack 服务接口
+ *
+ * 提供协议无关的 receive-pack 能力：
+ * - advertise(): 生成服务 ref 广告
+ * - handleRequest(): 处理客户端请求
+ */
+interface ReceivePackService {
+  /**
+   * 生成 ref 广告
+   */
+  advertise(): Buffer;
+  /**
+   * 处理请求
+   *
+   * @param body - 客户端请求体
+   * @returns 服务端响应
+   */
+  handleRequest(body: Buffer): Buffer;
+}
+/**
+ * 创建 Receive-Pack 服务实例
+ *
+ * @param backend - 仓库后端
+ * @param options - 处理选项
+ * @returns ReceivePackService 实例
+ *
+ * @example
+ * ```ts
+ * const service = createReceivePackService(backend);
+ * const advertise = service.advertise();
+ * const response = service.handleRequest(body);
+ * ```
+ */
+declare function createReceivePackService(backend: RepositoryBackend, options?: ReceivePackOptions): ReceivePackService;
+//#endregion
+export { ReceivePackService, createReceivePackService };

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

@@ -0,0 +1,39 @@
+import { advertiseReceivePack } from "./advertise.mjs";
+import { handleReceivePackRequest } from "./handler.mjs";
+//#region src/transport/server/receive-pack/service.ts
+/**
+* receive-pack 服务编排器
+*
+* 聚合 Git 协议 v1 receive-pack 的服务端能力：
+* - ref 广告生成
+* - push 请求处理
+*
+* 底层协议实现细节仍保留在各子模块中，
+* 本文件仅提供协议无关的服务接口和工厂。
+*/
+/**
+* 创建 Receive-Pack 服务实例
+*
+* @param backend - 仓库后端
+* @param options - 处理选项
+* @returns ReceivePackService 实例
+*
+* @example
+* ```ts
+* const service = createReceivePackService(backend);
+* const advertise = service.advertise();
+* const response = service.handleRequest(body);
+* ```
+*/
+function createReceivePackService(backend, options) {
+	return {
+		advertise() {
+			return advertiseReceivePack(backend);
+		},
+		handleRequest(body) {
+			return handleReceivePackRequest(backend, body, options);
+		}
+	};
+}
+//#endregion
+export { createReceivePackService };

package/dist/transport/server/receive-pack/types.d.mts

@@ -0,0 +1,56 @@
+import { SHA1 } from "../../../core/types.mjs";
+import { GitError } from "../../../core/errors.mjs";
+
+//#region src/transport/server/receive-pack/types.d.ts
+/**
+ * receive-pack 服务错误
+ *
+ * 当请求解析、处理或响应生成过程中遇到可预见的错误时抛出。
+ */
+declare class ReceivePackServiceError extends GitError {
+  constructor(message: string);
+}
+/**
+ * Receive-pack 命令（ref 更新）
+ *
+ * 表示客户端请求的一次 ref 变更。
+ */
+interface ReceivePackCommand {
+  /** 客户端声称的服务端当前哈希（新建时为 000...0） */
+  readonly oldHash: SHA1;
+  /** 要设置的目标哈希（删除时为 000...0） */
+  readonly newHash: SHA1;
+  /** 引用完整名称，如 "refs/heads/main" */
+  readonly refName: string;
+}
+/**
+ * 解析后的 receive-pack 请求
+ */
+interface ParsedReceivePackRequest {
+  /** 客户端能力列表（首行 NUL 后的内容） */
+  readonly capabilities: string[];
+  /** ref 更新命令列表 */
+  readonly commands: ReceivePackCommand[];
+  /** packfile 数据（可能为空） */
+  readonly packfile: Buffer;
+}
+/**
+ * 单个 ref 更新的处理结果
+ */
+interface ReceivePackUpdateResult {
+  readonly refName: string;
+  readonly success: boolean;
+  readonly error?: string;
+}
+/**
+ * receive-pack 处理选项
+ */
+interface ReceivePackOptions {
+  /**
+   * 是否拒绝非 fast-forward 推送（类似 receive.denyNonFastForwards）
+   * 默认 false
+   */
+  readonly denyNonFastForwards?: boolean;
+}
+//#endregion
+export { ParsedReceivePackRequest, ReceivePackCommand, ReceivePackOptions, ReceivePackServiceError, ReceivePackUpdateResult };

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

@@ -0,0 +1,25 @@
+import { GitError } from "../../../core/errors.mjs";
+import { sha1 } from "../../../core/types.mjs";
+//#region src/transport/server/receive-pack/types.ts
+/**
+* receive-pack 服务端类型定义与常量
+*/
+/** 零哈希（表示新建或删除引用） */
+const ZERO_HASH = sha1("0000000000000000000000000000000000000000");
+/** 服务端 agent 字符串 */
+const SERVER_AGENT = "nano-git/0.1";
+/** v1 广告中 prefix-ref 的 magic 名称 */
+const CAPABILITIES_REF = "capabilities^{}";
+/**
+* receive-pack 服务错误
+*
+* 当请求解析、处理或响应生成过程中遇到可预见的错误时抛出。
+*/
+var ReceivePackServiceError = class extends GitError {
+	constructor(message) {
+		super(`receive-pack: ${message}`);
+		this.name = "ReceivePackServiceError";
+	}
+};
+//#endregion
+export { CAPABILITIES_REF, ReceivePackServiceError, SERVER_AGENT, ZERO_HASH };