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
mainroot / apps / api / Git / GitEndpoints.cs
// SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
using System.Text;
using Microsoft.Extensions.Options;
namespace Progmasoft.Progmaweb.Api.Git;
/// <summary>A repository in a listing.</summary>
/// <param name="Name">Its name.</param>
/// <param name="Description">What it is.</param>
/// <param name="Homepage">Where it is developed, on GitHub.</param>
/// <param name="CloneUrl">Where it is cloned from.</param>
/// <param name="DefaultBranch">Its default branch.</param>
/// <param name="UpdatedAt">When its default branch last changed.</param>
internal sealed record GitRepositoryResponse(
string Name,
string Description,
string Homepage,
string CloneUrl,
string? DefaultBranch,
DateTimeOffset? UpdatedAt);
/// <summary>A section of the listing.</summary>
/// <param name="Name">Its heading.</param>
/// <param name="Repositories">Its repositories.</param>
internal sealed record GitSectionResponse(string Name, IReadOnlyList<GitRepositoryResponse> Repositories);
/// <summary>What is at a path of a commit.</summary>
/// <param name="Reference">The branch, tag or commit the request named.</param>
/// <param name="Commit">The commit it resolved to.</param>
/// <param name="Path">The path; empty for the root.</param>
/// <param name="Kind"><c>tree</c> or <c>blob</c>.</param>
/// <param name="Entries">The entries of a tree; null for a blob.</param>
/// <param name="Size">The size of a blob; null for a tree.</param>
/// <param name="IsBinary">Whether the blob is not text; a binary blob carries no text.</param>
/// <param name="Text">The text of a blob up to <see cref="GitReader.MaxTextBytes"/>.</param>
/// <param name="IsTruncated">Whether the text was cut.</param>
internal sealed record GitTreeResponse(
string Reference,
string Commit,
string Path,
string Kind,
IReadOnlyList<GitTreeEntry>? Entries,
long? Size,
bool IsBinary,
string? Text,
bool IsTruncated);
/// <summary>The read-only mirrors of git.progmasoft.com, for the pages of the Progmasoft site.</summary>
/// <remarks>
/// The pages are rendered by Next.js on the same host, which calls these endpoints on loopback. Two of them reach the
/// browser through Nginx: the raw files and the archives. Clones are served by git-http-backend, not here.
/// </remarks>
internal static class GitEndpoints
{
/// <summary>The prefix of every endpoint.</summary>
public const string Prefix = "/api/v1/git";
/// <summary>Maps the endpoints.</summary>
/// <param name="app">The application.</param>
public static void MapGitEndpoints(this WebApplication app)
{
RouteGroupBuilder api = app.MapGroup(Prefix + "/repositories").RequireRateLimiting("git");
api.MapGet("/", ListAsync);
api.MapGet("/{name}", ShowAsync);
api.MapGet("/{name}/refs", RefsAsync);
api.MapGet("/{name}/tree", TreeAsync);
api.MapGet("/{name}/log", LogAsync);
api.MapGet("/{name}/commits/{commit}", CommitAsync);
api.MapGet("/{name}/raw", RawAsync);
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,
IOptions<GitOptions> options,
CancellationToken cancellationToken)
{
List<GitSectionResponse> sections = [];
foreach (GitCatalogSection section in catalog.Sections())
{
List<GitRepositoryResponse> repositories = [];
foreach (GitCatalogRepository repository in section.Repositories)
{
if (catalog.Find(repository.Name) is not { } found)
{
continue;
}
repositories.Add(await DescribeAsync(git, options, found.Repository, found.MirrorPath, cancellationToken));
}
if (repositories.Count > 0)
{
sections.Add(new GitSectionResponse(section.Name, repositories));
}
}
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,
GitCatalogRepository repository,
string mirror,
CancellationToken cancellationToken)
{
string? branch = await git.DefaultBranchAsync(mirror, cancellationToken);
DateTimeOffset? updated = null;
if (branch is not null && await git.ResolveAsync(mirror, branch, cancellationToken) is { } head)
{
(IReadOnlyList<GitLogEntry> commits, _) = await git.LogAsync(mirror, head, "", 0, cancellationToken);
updated = commits.Count > 0 ? commits[0].Date : null;
}
return new GitRepositoryResponse(
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,
GitReader git,
IOptions<GitOptions> options,
CancellationToken cancellationToken) =>
catalog.Find(name) is { } found
? 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,
GitReader git,
CancellationToken cancellationToken)
{
if (catalog.Find(name) is not { } found)
{
return Results.NotFound();
}
(IReadOnlyList<GitRef> branches, IReadOnlyList<GitRef> tags) = await git.RefsAsync(found.MirrorPath, cancellationToken);
return Results.Ok(new { branches, tags });
}
/// <summary>Finds the mirror, the commit a reference names (the default branch without one) and checks a path.</summary>
private static async Task<(string Mirror, string Reference, string Commit, string Path)?> LocateAsync(
string name,
string? reference,
string? path,
GitCatalog catalog,
GitReader git,
CancellationToken cancellationToken)
{
string trimmed = (path ?? "").Trim('/');
if (catalog.Find(name) is not { } found || !GitReader.IsTreePath(trimmed))
{
return null;
}
string? named = string.IsNullOrEmpty(reference)
? await git.DefaultBranchAsync(found.MirrorPath, cancellationToken)
: reference;
if (named is null || await git.ResolveAsync(found.MirrorPath, named, cancellationToken) is not { } commit)
{
return null;
}
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,
string? path,
GitCatalog catalog,
GitReader git,
CancellationToken cancellationToken)
{
if (await LocateAsync(name, @ref, path, catalog, git, cancellationToken) is not { } at)
{
return Results.NotFound();
}
string? kind = await git.KindAsync(at.Mirror, at.Commit, at.Path, cancellationToken);
if (kind == "tree")
{
IReadOnlyList<GitTreeEntry> entries = await git.TreeAsync(at.Mirror, at.Commit, at.Path, cancellationToken);
return Results.Ok(new GitTreeResponse(at.Reference, at.Commit, at.Path, "tree", entries, null, false, null, false));
}
if (kind != "blob")
{
return Results.NotFound();
}
long size = await git.SizeAsync(at.Mirror, at.Commit, at.Path, cancellationToken);
(byte[] bytes, bool isTruncated) = await git.BlobAsync(at.Mirror, at.Commit, at.Path, GitReader.MaxTextBytes, cancellationToken);
bool isBinary = IsBinary(bytes);
return Results.Ok(new GitTreeResponse(
at.Reference, at.Commit, at.Path, "blob", null, size, isBinary, isBinary ? null : Encoding.UTF8.GetString(bytes), isTruncated));
}
/// <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,
string? path,
int? page,
GitCatalog catalog,
GitReader git,
CancellationToken cancellationToken)
{
if (page is < 0 or > 10_000
|| await LocateAsync(name, @ref, path, catalog, git, cancellationToken) is not { } at)
{
return Results.NotFound();
}
(IReadOnlyList<GitLogEntry> commits, bool hasMore) =
await git.LogAsync(at.Mirror, at.Commit, at.Path, page ?? 0, cancellationToken);
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,
GitCatalog catalog,
GitReader git,
CancellationToken cancellationToken)
{
if (!GitReader.IsCommitId(commit)
|| catalog.Find(name) is not { } found
|| await git.ResolveAsync(found.MirrorPath, commit, cancellationToken) is not { } resolved)
{
return Results.NotFound();
}
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,
string? path,
HttpContext context,
GitCatalog catalog,
GitReader git,
CancellationToken cancellationToken)
{
if (await LocateAsync(name, @ref, path, catalog, git, cancellationToken) is not { } at
|| at.Path.Length == 0
|| await git.KindAsync(at.Mirror, at.Commit, at.Path, cancellationToken) != "blob")
{
return Results.NotFound();
}
long size = await git.SizeAsync(at.Mirror, at.Commit, at.Path, cancellationToken);
if (size > GitReader.MaxRawBytes)
{
return Results.StatusCode(StatusCodes.Status413PayloadTooLarge);
}
(byte[] bytes, _) = await git.BlobAsync(at.Mirror, at.Commit, at.Path, GitReader.MaxRawBytes, cancellationToken);
// Raw files are never rendered by the browser: text is plain text, anything else is a download, and the
// content security policy of the API allows nothing to run.
context.Response.Headers.ContentDisposition = IsBinary(bytes)
? $"attachment; filename=\"{SafeFileName(at.Path)}\""
: "inline";
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,
HttpContext context,
GitCatalog catalog,
GitReader git,
CancellationToken cancellationToken)
{
if (await LocateAsync(name, @ref, "", catalog, git, cancellationToken) is not { } at)
{
context.Response.StatusCode = StatusCodes.Status404NotFound;
return;
}
string label = SafeFileName(at.Reference.Replace('/', '-'));
string prefix = $"{name}-{label}";
context.Response.ContentType = "application/gzip";
context.Response.Headers.ContentDisposition = $"attachment; filename=\"{prefix}.tar.gz\"";
await git.ArchiveAsync(at.Mirror, at.Commit, prefix + "/", context.Response.Body, cancellationToken);
}
/// <summary>The last segment of a path with only safe characters, for a Content-Disposition file name.</summary>
internal static string SafeFileName(string path)
{
string last = path[(path.LastIndexOf('/') + 1)..];
string safe = new([.. last.Select(c => char.IsAsciiLetterOrDigit(c) || c is '.' or '-' or '_' or '+' ? c : '_')]);
return safe.Length == 0 ? "file" : safe;
}
}
/// <summary>Keeps the Git endpoints on git.progmasoft.com and loopback, and everything else off that host.</summary>
/// <param name="next">The rest of the pipeline.</param>
/// <param name="options">The host of the mirrors.</param>
internal sealed class GitHostFilter(RequestDelegate next, IOptions<GitOptions> options)
{
/// <summary>Answers 404 for a Git path on another host, or another path on the Git host.</summary>
/// <param name="context">The request.</param>
/// <returns>A task that completes when the request has been answered.</returns>
public Task InvokeAsync(HttpContext context)
{
PathString path = context.Request.Path;
string host = context.Request.Host.Host;
bool isGitPath = path.StartsWithSegments(GitEndpoints.Prefix, StringComparison.OrdinalIgnoreCase);
bool isHealth = path.StartsWithSegments("/health", StringComparison.OrdinalIgnoreCase);
bool isGitHost = string.Equals(host, options.Value.Host, StringComparison.OrdinalIgnoreCase);
bool isLoopback = host is "127.0.0.1" or "localhost" or "::1" or "[::1]";
bool allowed = isGitHost ? isGitPath || isHealth : !isGitPath || isLoopback;
if (allowed)
{
return next(context);
}
context.Response.StatusCode = StatusCodes.Status404NotFound;
return Task.CompletedTask;
}
}