// SPDX-FileCopyrightText: 2026 Progmasoft // SPDX-License-Identifier: AGPL-3.0-or-later using System.Diagnostics; using System.Globalization; using System.Text; using System.Text.RegularExpressions; using Microsoft.Extensions.Options; namespace Progmasoft.Progmaweb.Api.Git; /// A branch or a tag. /// Its short name. /// The commit it names. /// When that commit was made, or the tag was created. /// The first line of its message. internal sealed record GitRef(string Name, string Commit, DateTimeOffset Date, string Subject); /// One commit of a log. /// Its identifier. /// Its author's name. /// When it was authored. /// The first line of its message. internal sealed record GitLogEntry(string Commit, string Author, DateTimeOffset Date, string Subject); /// One entry of a tree. /// Its name in the tree. /// tree, blob, link or submodule. /// The size of a blob in bytes; null otherwise. internal sealed record GitTreeEntry(string Name, string Kind, long? Size); /// A commit with its message and changes. /// Its identifier. /// Its parents. /// Its author's name. /// When it was authored. /// Its committer's name. /// When it was committed. /// Its whole message. /// The patch against its first parent, or the whole tree for a root commit. /// Whether the patch was cut at . internal sealed record GitCommitDetails( string Commit, IReadOnlyList Parents, string Author, DateTimeOffset AuthorDate, string Committer, DateTimeOffset CommitDate, string Message, string Diff, bool IsDiffTruncated); /// Reads a bare mirror with the Git program. /// /// /// Every argument comes from a resolved commit identifier, a validated name or a validated path, and is passed as /// one element of the argument list, never through a shell; options end before anything a request gave. Git runs /// without the system and global configuration, without a terminal, and for at most . /// /// /// The mirrors belong to the user that fetches them, so this reader trusts them through safe.directory for /// its own runs only, as git-http-backend does in the Nginx configuration. /// /// /// Where Git is. internal sealed partial class GitReader(IOptions options) { /// How long one run of Git may take. public static readonly TimeSpan Timeout = TimeSpan.FromSeconds(15); /// The largest file shown as text in a page. public const int MaxTextBytes = 1024 * 1024; /// The largest patch shown in a page. public const int MaxDiffBytes = 512 * 1024; /// The largest file served raw. public const long MaxRawBytes = 32L * 1024 * 1024; /// Commits per page of a log. public const int LogPageSize = 50; /// Matches a full commit identifier, SHA-1 or SHA-256. /// The compiled expression. [GeneratedRegex("^(?:[0-9a-f]{40}|[0-9a-f]{64})$", RegexOptions.CultureInvariant)] private static partial Regex CommitPattern(); /// Matches the characters a branch or tag name of these repositories may have. /// The compiled expression. [GeneratedRegex("^[A-Za-z0-9._+/-]{1,200}$", RegexOptions.CultureInvariant)] private static partial Regex RefPattern(); /// Whether a text is a full commit identifier. /// The text. /// when it is one. public static bool IsCommitId(string text) => CommitPattern().IsMatch(text); /// Whether a text may name a branch or a tag: Git's rules, as far as a request needs them. /// The text. /// when it may. public static bool IsRefName(string name) => RefPattern().IsMatch(name) && !name.StartsWith('-') && !name.StartsWith('/') && !name.EndsWith('/') && !name.EndsWith(".lock", StringComparison.Ordinal) && !name.Contains("..", StringComparison.Ordinal) && !name.Contains("//", StringComparison.Ordinal) && !name.Split('/').Any(part => part.StartsWith('.')); /// Whether a text is a path inside a tree: segments without ., .. or control characters. /// The path, without a leading or trailing slash; empty for the root. /// when it is one. public static bool IsTreePath(string path) => path.Length == 0 || (path.Length <= 4096 && path.Split('/').All(part => part.Length > 0 && part != "." && part != ".." && !part.Any(char.IsControl))); /// The default branch of a mirror. /// The path of the mirror. /// Cancels the run. /// Its name, or when HEAD names no branch. public async Task DefaultBranchAsync(string mirror, CancellationToken cancellationToken) { GitResult result = await RunAsync(mirror, ["symbolic-ref", "--quiet", "--short", "HEAD"], cancellationToken); return result.Ok ? result.Text.Trim() : null; } /// Resolves a branch, a tag or a full commit identifier to a commit. /// The path of the mirror. /// What a request named. /// Cancels the run. /// The commit, or when the reference names none. public async Task ResolveAsync(string mirror, string reference, CancellationToken cancellationToken) { string[] candidates = IsCommitId(reference) ? [reference] : IsRefName(reference) ? [$"refs/heads/{reference}", $"refs/tags/{reference}"] : []; foreach (string candidate in candidates) { GitResult result = await RunAsync( mirror, ["rev-parse", "--verify", "--quiet", "--end-of-options", candidate + "^{commit}"], cancellationToken); if (result.Ok) { return result.Text.Trim(); } } return null; } /// The branches and the tags of a mirror, the newest first. /// The path of the mirror. /// Cancels the run. /// The branches and the tags. public async Task<(IReadOnlyList Branches, IReadOnlyList Tags)> RefsAsync( string mirror, CancellationToken cancellationToken) { GitResult result = await RunAsync( mirror, [ "for-each-ref", "--sort=-creatordate", "--format=%(refname)%00%(if)%(*objectname)%(then)%(*objectname)%(else)%(objectname)%(end)%00%(creatordate:iso-strict)%00%(contents:subject)%1e", "refs/heads", "refs/tags" ], cancellationToken); List branches = []; List tags = []; foreach (string record in Records(result.Text)) { string[] fields = record.Split('\0'); if (fields.Length < 4) { continue; } if (fields[0].StartsWith("refs/heads/", StringComparison.Ordinal)) { branches.Add(new GitRef(fields[0]["refs/heads/".Length..], fields[1], Date(fields[2]), fields[3])); } else if (fields[0].StartsWith("refs/tags/", StringComparison.Ordinal)) { tags.Add(new GitRef(fields[0]["refs/tags/".Length..], fields[1], Date(fields[2]), fields[3])); } } return (branches, tags); } /// The kind of the object at a path of a commit. /// The path of the mirror. /// A resolved commit. /// A valid tree path. /// Cancels the run. /// tree, blob, or when nothing is there. public async Task KindAsync(string mirror, string commit, string path, CancellationToken cancellationToken) { GitResult result = await RunAsync(mirror, ["cat-file", "-t", "--end-of-options", $"{commit}:{path}"], cancellationToken); return result.Ok ? result.Text.Trim() : null; } /// The entries of a tree: directories first, then by name. /// The path of the mirror. /// A resolved commit. /// A valid tree path that names a tree. /// Cancels the run. /// The entries. public async Task> TreeAsync( string mirror, string commit, string path, CancellationToken cancellationToken) { GitResult result = await RunAsync(mirror, ["ls-tree", "-l", "-z", "--end-of-options", $"{commit}:{path}"], cancellationToken); List entries = []; foreach (string line in result.Text.Split('\0', StringSplitOptions.RemoveEmptyEntries)) { // SP SP SP+ TAB int tab = line.IndexOf('\t', StringComparison.Ordinal); if (tab < 0) { continue; } string[] meta = line[..tab].Split(' ', StringSplitOptions.RemoveEmptyEntries); string name = line[(tab + 1)..]; string kind = meta[0] switch { "040000" => "tree", "120000" => "link", "160000" => "submodule", _ => "blob" }; long? size = kind is "blob" or "link" && long.TryParse(meta[^1], CultureInfo.InvariantCulture, out long bytes) ? bytes : null; entries.Add(new GitTreeEntry(name, kind, size)); } return [.. entries.OrderBy(entry => entry.Kind == "tree" ? 0 : 1).ThenBy(entry => entry.Name, StringComparer.Ordinal)]; } /// The size of a blob. /// The path of the mirror. /// A resolved commit. /// A valid tree path that names a blob. /// Cancels the run. /// The size in bytes. public async Task SizeAsync(string mirror, string commit, string path, CancellationToken cancellationToken) { GitResult result = await RunAsync(mirror, ["cat-file", "-s", "--end-of-options", $"{commit}:{path}"], cancellationToken); return long.Parse(result.Text.Trim(), CultureInfo.InvariantCulture); } /// The content of a blob, up to a limit. /// The path of the mirror. /// A resolved commit. /// A valid tree path that names a blob. /// The most bytes to read. /// Cancels the run. /// The bytes, and whether there were more. public async Task<(byte[] Bytes, bool IsTruncated)> BlobAsync( string mirror, string commit, string path, long limit, CancellationToken cancellationToken) { GitResult result = await RunAsync(mirror, ["cat-file", "blob", "--end-of-options", $"{commit}:{path}"], cancellationToken, limit); return (result.Bytes, result.IsTruncated); } /// A page of the log of a commit, of a path in it when one is given. /// The path of the mirror. /// A resolved commit. /// A valid tree path, or empty for the whole tree. /// The page, from zero. /// Cancels the run. /// The commits of the page, and whether another page follows. public async Task<(IReadOnlyList Commits, bool HasMore)> LogAsync( string mirror, string commit, string path, int page, CancellationToken cancellationToken) { List arguments = [ "log", "--format=%H%x00%an%x00%aI%x00%s%x1e", $"--skip={page * LogPageSize}", $"--max-count={LogPageSize + 1}", "--end-of-options", commit ]; if (path.Length > 0) { arguments.AddRange(["--", path]); } GitResult result = await RunAsync(mirror, arguments, cancellationToken); List commits = []; foreach (string record in Records(result.Text)) { string[] fields = record.Split('\0'); if (fields.Length >= 4) { commits.Add(new GitLogEntry(fields[0], fields[1], Date(fields[2]), fields[3])); } } bool hasMore = commits.Count > LogPageSize; return (hasMore ? commits[..LogPageSize] : commits, hasMore); } /// A commit, its message and its patch. /// The path of the mirror. /// A resolved commit. /// Cancels the runs. /// The commit. public async Task CommitAsync(string mirror, string commit, CancellationToken cancellationToken) { GitResult header = await RunAsync( mirror, ["show", "-s", "--format=%H%x00%P%x00%an%x00%aI%x00%cn%x00%cI%x00%B", "--end-of-options", commit], cancellationToken); string[] fields = header.Text.Split('\0', 7); GitResult diff = await RunAsync( mirror, ["diff-tree", "--patch", "--stat", "--no-color", "--no-ext-diff", "--find-renames", "--root", "--no-commit-id", "--end-of-options", commit], cancellationToken, MaxDiffBytes); return new GitCommitDetails( fields[0], fields[1].Split(' ', StringSplitOptions.RemoveEmptyEntries), fields[2], Date(fields[3]), fields[4], Date(fields[5]), fields[6].TrimEnd(), Encoding.UTF8.GetString(diff.Bytes), diff.IsTruncated); } /// Writes a gzip-compressed tar archive of a commit. /// The path of the mirror. /// A resolved commit. /// The directory every file is put in, such as tazel-main/. /// Where the archive goes. /// Cancels the run. /// A task that completes when the archive is written. public async Task ArchiveAsync(string mirror, string commit, string prefix, Stream output, CancellationToken cancellationToken) { using Process process = Start(mirror, ["archive", "--format=tar.gz", $"--prefix={prefix}", "--end-of-options", commit]); using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); timeout.CancelAfter(TimeSpan.FromMinutes(2)); try { Task errors = process.StandardError.ReadToEndAsync(timeout.Token); await process.StandardOutput.BaseStream.CopyToAsync(output, timeout.Token); await process.WaitForExitAsync(timeout.Token); if (process.ExitCode != 0) { throw new IOException($"git archive exited with {process.ExitCode}: {(await errors).Trim()}"); } } finally { Stop(process); } } /// The result of one run. /// Whether Git exited with 0. /// What it wrote, up to the limit. /// Whether it wrote more than the limit. private sealed record GitResult(bool Ok, byte[] Bytes, bool IsTruncated) { /// What Git wrote, as UTF-8 text. public string Text => Encoding.UTF8.GetString(Bytes); } /// Runs Git on a mirror and reads what it writes, up to a limit. /// The path of the mirror. /// The arguments after the global options. /// Cancels the run. /// The most bytes to read; Git is stopped past it. /// The result. private async Task RunAsync( string mirror, IReadOnlyList arguments, CancellationToken cancellationToken, long limit = 16 * 1024 * 1024) { using Process process = Start(mirror, arguments); using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); timeout.CancelAfter(Timeout); try { Task drain = process.StandardError.ReadToEndAsync(timeout.Token); using MemoryStream bytes = new(); byte[] buffer = new byte[81920]; bool isTruncated = false; Stream stdout = process.StandardOutput.BaseStream; int read; while ((read = await stdout.ReadAsync(buffer, timeout.Token)) > 0) { long room = limit - bytes.Length; if (read > room) { bytes.Write(buffer, 0, (int)Math.Max(room, 0)); isTruncated = true; break; } bytes.Write(buffer, 0, read); } if (isTruncated) { Stop(process); return new GitResult(true, bytes.ToArray(), true); } await process.WaitForExitAsync(timeout.Token); await drain; return new GitResult(process.ExitCode == 0, bytes.ToArray(), false); } finally { Stop(process); } } /// Starts Git on a mirror, without a shell, in a cleared environment. /// The path of the mirror. /// The arguments after the global options. /// The process, its output redirected. private Process Start(string mirror, IReadOnlyList arguments) { ProcessStartInfo start = new(options.Value.GitPath) { RedirectStandardOutput = true, RedirectStandardError = true, RedirectStandardInput = false, UseShellExecute = false, WorkingDirectory = mirror }; foreach (string argument in (string[])["-c", $"safe.directory={mirror}", "-c", "core.quotePath=false", "--git-dir", mirror, "--no-pager"]) { start.ArgumentList.Add(argument); } foreach (string argument in arguments) { start.ArgumentList.Add(argument); } start.Environment.Clear(); start.Environment["PATH"] = "/usr/bin:/bin"; start.Environment["LANG"] = "C.UTF-8"; start.Environment["GIT_CONFIG_NOSYSTEM"] = "1"; start.Environment["GIT_CONFIG_GLOBAL"] = "/dev/null"; start.Environment["GIT_TERMINAL_PROMPT"] = "0"; start.Environment["GIT_NO_REPLACE_OBJECTS"] = "1"; return Process.Start(start) ?? throw new InvalidOperationException("Git did not start."); } /// Kills a run that has not exited. /// The run. private static void Stop(Process process) { try { if (!process.HasExited) { process.Kill(); } } catch (InvalidOperationException) { // It exited between the check and the kill. } } /// Splits output into the records a format ended with the record separator. /// The output. /// The records that are not empty. private static IEnumerable Records(string text) => text.Split('\u001e').Select(record => record.TrimStart('\n')).Where(record => record.Length > 0); /// Reads a strict ISO 8601 date Git wrote. /// The date. /// The date, or the Unix epoch when it cannot be read. private static DateTimeOffset Date(string text) => DateTimeOffset.TryParse(text, CultureInfo.InvariantCulture, DateTimeStyles.None, out DateTimeOffset date) ? date : DateTimeOffset.UnixEpoch; }