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
- Commit
f103618012d6da7f74a6a971830802e10064d540- Author
- Leitwolf11 ·
- Parents
c32d79b7b473
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.