Progmasoft Git

progmaweb

The site and account service of Progmasoft: a Next.js frontend and an ASP.NET Core API.

Clonegit clone https://git.progmasoft.com/progmaweb

Document every member of the Git endpoints

The API reference check wants a summary on each declaration and the
namespace: the private helpers of the catalog, the reader and the
endpoints get theirs, the namespace a page in docs/api/namespaces, and
the three generated regular expressions are left out of the reference
like the one of AccountNamePolicy.
Commit
f103618012d6da7f74a6a971830802e10064d540
Author
Leitwolf11 ·
Parents
c32d79b7b473

Files · Download .tar.gz

Changes

 apps/api/Git/GitCatalog.cs                         | 10 ++-
 apps/api/Git/GitEndpoints.cs                       | 74 ++++++++++++++++++++++
 apps/api/Git/GitReader.cs                          | 25 +++++++-
 docs/api/filterConfig.yml                          |  6 ++
 .../api/namespaces/Progmasoft.Progmaweb.Api.Git.md |  9 +++
 5 files changed, 121 insertions(+), 3 deletions(-)

diff --git a/apps/api/Git/GitCatalog.cs b/apps/api/Git/GitCatalog.cs
index e79a82a..89a80f9 100644
--- a/apps/api/Git/GitCatalog.cs
+++ b/apps/api/Git/GitCatalog.cs
@@ -44,13 +44,17 @@ internal sealed record GitCatalogSection(string Name, IReadOnlyList<GitCatalogRe
 /// <param name="options">Where the catalog is.</param>
 internal sealed partial class GitCatalog(IOptions<GitOptions> options)
 {
+    /// <summary>How the catalog file is read: property names in any case.</summary>
     private static readonly JsonSerializerOptions JsonOptions = new() { PropertyNameCaseInsensitive = true };
 
+    /// <summary>Guards <see cref="cached"/>.</summary>
     private readonly Lock gate = new();
 
+    /// <summary>The catalog as last read, with the time its file was written then.</summary>
     private (DateTime Written, IReadOnlyList<GitCatalogSection> Sections)? cached;
 
-    /// <summary>Whether a text is a repository name: what GitHub allows, without a leading dot.</summary>
+    /// <summary>Matches a repository name: what GitHub allows, without a leading dot.</summary>
+    /// <returns>The compiled expression.</returns>
     [GeneratedRegex("^[A-Za-z0-9_-][A-Za-z0-9._-]{0,99}$", RegexOptions.CultureInvariant)]
     private static partial Regex NamePattern();
 
@@ -108,6 +112,10 @@ internal sealed partial class GitCatalog(IOptions<GitOptions> options)
     /// <returns>The path.</returns>
     public string MirrorOf(string name) => Path.Combine(options.Value.MirrorsPath, name + ".git");
 
+    /// <summary>Reads and checks the catalog file.</summary>
+    /// <param name="path">The file.</param>
+    /// <returns>Its sections.</returns>
+    /// <exception cref="InvalidDataException">The file is empty or names something that is not a repository name.</exception>
     private static IReadOnlyList<GitCatalogSection> Read(string path)
     {
         using FileStream stream = File.OpenRead(path);
diff --git a/apps/api/Git/GitEndpoints.cs b/apps/api/Git/GitEndpoints.cs
index c5cd629..e034646 100644
--- a/apps/api/Git/GitEndpoints.cs
+++ b/apps/api/Git/GitEndpoints.cs
@@ -72,10 +72,23 @@ internal static class GitEndpoints
         api.MapGet("/{name}/archive", ArchiveAsync);
     }
 
+    /// <summary>Where a repository is developed.</summary>
+    /// <param name="name">Its name.</param>
+    /// <returns>Its address on GitHub.</returns>
     private static string Homepage(string name) => $"https://github.com/Progmasoft/{name}";
 
+    /// <summary>Where a repository is cloned from.</summary>
+    /// <param name="options">The host of the mirrors.</param>
+    /// <param name="name">Its name.</param>
+    /// <returns>Its address on git.progmasoft.com.</returns>
     private static string CloneUrl(IOptions<GitOptions> options, string name) => $"https://{options.Value.Host}/{name}";
 
+    /// <summary>The sections of the catalog with their mirrored repositories.</summary>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="options">The host of the mirrors.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>The sections.</returns>
     private static async Task<IResult> ListAsync(
         GitCatalog catalog,
         GitReader git,
@@ -105,6 +118,13 @@ internal static class GitEndpoints
         return Results.Ok(sections);
     }
 
+    /// <summary>Describes a repository: its addresses, default branch and when that last changed.</summary>
+    /// <param name="git">The reader.</param>
+    /// <param name="options">The host of the mirrors.</param>
+    /// <param name="repository">The repository.</param>
+    /// <param name="mirror">The path of its mirror.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>The description.</returns>
     private static async Task<GitRepositoryResponse> DescribeAsync(
         GitReader git,
         IOptions<GitOptions> options,
@@ -124,6 +144,13 @@ internal static class GitEndpoints
             repository.Name, repository.Description, Homepage(repository.Name), CloneUrl(options, repository.Name), branch, updated);
     }
 
+    /// <summary>One repository.</summary>
+    /// <param name="name">Its name.</param>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="options">The host of the mirrors.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>The repository, or 404.</returns>
     private static async Task<IResult> ShowAsync(
         string name,
         GitCatalog catalog,
@@ -134,6 +161,12 @@ internal static class GitEndpoints
             ? Results.Ok(await DescribeAsync(git, options, found.Repository, found.MirrorPath, cancellationToken))
             : Results.NotFound();
 
+    /// <summary>The branches and the tags of a repository.</summary>
+    /// <param name="name">Its name.</param>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>The branches and tags, or 404.</returns>
     private static async Task<IResult> RefsAsync(
         string name,
         GitCatalog catalog,
@@ -175,6 +208,14 @@ internal static class GitEndpoints
         return (found.MirrorPath, named, commit, trimmed);
     }
 
+    /// <summary>A directory or a file of a branch, tag or commit.</summary>
+    /// <param name="name">The repository.</param>
+    /// <param name="ref">The branch, tag or commit; the default branch without one.</param>
+    /// <param name="path">The path; the root without one.</param>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>What is there, or 404.</returns>
     private static async Task<IResult> TreeAsync(
         string name,
         string? @ref,
@@ -210,6 +251,15 @@ internal static class GitEndpoints
     /// <summary>Whether bytes are not text: a NUL in the first 8000, as Git decides.</summary>
     internal static bool IsBinary(ReadOnlySpan<byte> bytes) => bytes[..Math.Min(bytes.Length, 8000)].Contains((byte)0);
 
+    /// <summary>A page of the commits of a branch, tag or commit, of a path in it when one is given.</summary>
+    /// <param name="name">The repository.</param>
+    /// <param name="ref">The branch, tag or commit; the default branch without one.</param>
+    /// <param name="path">The path; the whole tree without one.</param>
+    /// <param name="page">The page, from zero.</param>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>The commits, or 404.</returns>
     private static async Task<IResult> LogAsync(
         string name,
         string? @ref,
@@ -230,6 +280,13 @@ internal static class GitEndpoints
         return Results.Ok(new { reference = at.Reference, commit = at.Commit, path = at.Path, page = page ?? 0, commits, hasMore });
     }
 
+    /// <summary>A commit with its message and patch.</summary>
+    /// <param name="name">The repository.</param>
+    /// <param name="commit">The full commit identifier.</param>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>The commit, or 404.</returns>
     private static async Task<IResult> CommitAsync(
         string name,
         string commit,
@@ -247,6 +304,15 @@ internal static class GitEndpoints
         return Results.Ok(await git.CommitAsync(found.MirrorPath, resolved, cancellationToken));
     }
 
+    /// <summary>A file as it is: plain text, or a download when it is binary.</summary>
+    /// <param name="name">The repository.</param>
+    /// <param name="ref">The branch, tag or commit; the default branch without one.</param>
+    /// <param name="path">The path of the file.</param>
+    /// <param name="context">The request, for the Content-Disposition header.</param>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>The file, 404, or 413 past <see cref="GitReader.MaxRawBytes"/>.</returns>
     private static async Task<IResult> RawAsync(
         string name,
         string? @ref,
@@ -278,6 +344,14 @@ internal static class GitEndpoints
         return Results.Bytes(bytes, IsBinary(bytes) ? "application/octet-stream" : "text/plain; charset=utf-8");
     }
 
+    /// <summary>Writes a <c>.tar.gz</c> of a branch, tag or commit.</summary>
+    /// <param name="name">The repository.</param>
+    /// <param name="ref">The branch, tag or commit; the default branch without one.</param>
+    /// <param name="context">The request, which the archive is written to.</param>
+    /// <param name="catalog">The catalog.</param>
+    /// <param name="git">The reader.</param>
+    /// <param name="cancellationToken">Cancels the request.</param>
+    /// <returns>A task that completes when the archive is written.</returns>
     private static async Task ArchiveAsync(
         string name,
         string? @ref,
diff --git a/apps/api/Git/GitReader.cs b/apps/api/Git/GitReader.cs
index e36665f..b601882 100644
--- a/apps/api/Git/GitReader.cs
+++ b/apps/api/Git/GitReader.cs
@@ -80,11 +80,13 @@ internal sealed partial class GitReader(IOptions<GitOptions> options)
     /// <summary>Commits per page of a log.</summary>
     public const int LogPageSize = 50;
 
-    /// <summary>A full commit identifier, SHA-1 or SHA-256.</summary>
+    /// <summary>Matches a full commit identifier, SHA-1 or SHA-256.</summary>
+    /// <returns>The compiled expression.</returns>
     [GeneratedRegex("^(?:[0-9a-f]{40}|[0-9a-f]{64})$", RegexOptions.CultureInvariant)]
     private static partial Regex CommitPattern();
 
-    /// <summary>The characters a branch or tag name of these repositories may have.</summary>
+    /// <summary>Matches the characters a branch or tag name of these repositories may have.</summary>
+    /// <returns>The compiled expression.</returns>
     [GeneratedRegex("^[A-Za-z0-9._+/-]{1,200}$", RegexOptions.CultureInvariant)]
     private static partial Regex RefPattern();
 
@@ -373,9 +375,16 @@ internal sealed partial class GitReader(IOptions<GitOptions> options)
     /// <param name="IsTruncated">Whether it wrote more than the limit.</param>
     private sealed record GitResult(bool Ok, byte[] Bytes, bool IsTruncated)
     {
+        /// <summary>What Git wrote, as UTF-8 text.</summary>
         public string Text => Encoding.UTF8.GetString(Bytes);
     }
 
+    /// <summary>Runs Git on a mirror and reads what it writes, up to a limit.</summary>
+    /// <param name="mirror">The path of the mirror.</param>
+    /// <param name="arguments">The arguments after the global options.</param>
+    /// <param name="cancellationToken">Cancels the run.</param>
+    /// <param name="limit">The most bytes to read; Git is stopped past it.</param>
+    /// <returns>The result.</returns>
     private async Task<GitResult> RunAsync(
         string mirror,
         IReadOnlyList<string> arguments,
@@ -422,6 +431,10 @@ internal sealed partial class GitReader(IOptions<GitOptions> options)
         }
     }
 
+    /// <summary>Starts Git on a mirror, without a shell, in a cleared environment.</summary>
+    /// <param name="mirror">The path of the mirror.</param>
+    /// <param name="arguments">The arguments after the global options.</param>
+    /// <returns>The process, its output redirected.</returns>
     private Process Start(string mirror, IReadOnlyList<string> arguments)
     {
         ProcessStartInfo start = new(options.Value.GitPath)
@@ -452,6 +465,8 @@ internal sealed partial class GitReader(IOptions<GitOptions> options)
         return Process.Start(start) ?? throw new InvalidOperationException("Git did not start.");
     }
 
+    /// <summary>Kills a run that has not exited.</summary>
+    /// <param name="process">The run.</param>
     private static void Stop(Process process)
     {
         try
@@ -467,9 +482,15 @@ internal sealed partial class GitReader(IOptions<GitOptions> options)
         }
     }
 
+    /// <summary>Splits output into the records a format ended with the record separator.</summary>
+    /// <param name="text">The output.</param>
+    /// <returns>The records that are not empty.</returns>
     private static IEnumerable<string> Records(string text) =>
         text.Split('\u001e').Select(record => record.TrimStart('\n')).Where(record => record.Length > 0);
 
+    /// <summary>Reads a strict ISO 8601 date Git wrote.</summary>
+    /// <param name="text">The date.</param>
+    /// <returns>The date, or the Unix epoch when it cannot be read.</returns>
     private static DateTimeOffset Date(string text) =>
         DateTimeOffset.TryParse(text, CultureInfo.InvariantCulture, DateTimeStyles.None, out DateTimeOffset date)
             ? date
diff --git a/docs/api/filterConfig.yml b/docs/api/filterConfig.yml
index 25a4b3a..0966cee 100644
--- a/docs/api/filterConfig.yml
+++ b/docs/api/filterConfig.yml
@@ -12,3 +12,9 @@ apiRules:
   - exclude:
       uidRegex: ^Progmasoft\.Progmaweb\.Api\.Accounts\.AccountNamePolicy\.CanonicalPattern$
       type: Method
+  - exclude:
+      uidRegex: ^Progmasoft\.Progmaweb\.Api\.Git\.GitCatalog\.NamePattern$
+      type: Method
+  - exclude:
+      uidRegex: ^Progmasoft\.Progmaweb\.Api\.Git\.GitReader\.(CommitPattern|RefPattern)$
+      type: Method
diff --git a/docs/api/namespaces/Progmasoft.Progmaweb.Api.Git.md b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Git.md
new file mode 100644
index 0000000..b76ff6e
--- /dev/null
+++ b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Git.md
@@ -0,0 +1,9 @@
+---
+uid: Progmasoft.Progmaweb.Api.Git
+summary: *content
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+The read-only mirrors of git.progmasoft.com: the catalog of repositories, the reader that runs Git on the bare mirrors with checked arguments, and the endpoints under `/api/v1/git/repositories` that the pages of the Next.js site and Nginx call.