Pmad.Git.HttpServer 0.1.112

Pmad.Git.HttpServer

Pmad.Git.HttpServer is an ASP.NET Core library that lets git synchronize with a server side stored local repository using the Git Smart HTTP protocol.

Getting Started

1. Add a reference to Pmad.Git.HttpServer in your ASP.NET Core application.
2. Register the endpoints inside Program.cs:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGitSmartHttp(options =>
{
    options.RepositoryRoot = "/srv/git";
});

var app = builder.Build();
app.MapGitSmartHttp();
app.Run();

With the sample above, git clients can clone/fetch repositories stored under /srv/git using the Smart HTTP endpoints (/git/{repository}.git/info/refs, /git/{repository}.git/git-upload-pack).

Configuration

GitSmartHttpOptions controls behavior:

• RepositoryRoot: Absolute path containing repositories. Mandatory.
• EnableUploadPack: Allows git-upload-pack (fetch/clone). Enabled by default.
• EnableReceivePack: Allows git-receive-pack (push). Disabled by default.
• Agent: String advertised to clients (shown by git clone --verbose).
• AuthorizeAsync: Optional callback to allow/deny access per request. Receives the operation type (Read or Write) to distinguish between fetch/clone and push operations. By default, only read operations are allowed.
• RepositoryNameNormalizer: Optional callback to sanitize or transform repository names before file-system access. Applied after the .git suffix is removed from the repository name.
• RepositoryResolver: Callback to resolve the repository name from the HTTP context. By default, extracts the repository route parameter.
• OnReceivePackCompleted: Optional callback invoked after a push operation whenever at least one reference update succeeds (including partial success). The list passed to the callback contains only the successfully updated references. This allows the host application to perform cache invalidation or trigger other post-push actions.
• RepositoryNameValidator: Optional callback to validate repository names for security. By default only allows alphanumeric characters, hyphens, underscores, and forward slashes (no leading, trailing, or repeated slashes). Host applications can override this to allow additional characters.

Enabling Push Operations

By default, push operations are restricted for security. To enable push, you need to:

1. Set EnableReceivePack = true
2. Provide an AuthorizeAsync callback that allows write operations for authorized users

builder.Services.AddGitSmartHttp(options =>
{
    options.RepositoryRoot = "/srv/git";
    options.EnableReceivePack = true;
    options.AuthorizeAsync = async (context, repositoryName, operation, cancellationToken) =>
    {
        // Allow read for everyone
        if (operation == GitOperation.Read)
            return true;
        
        // Only allow write for authenticated users
        return context.User.Identity?.IsAuthenticated == true;
    };
});

Push Notification

When push operations are enabled, you can be notified when a push completes (including partial success) to invalidate application caches or trigger webhooks:

builder.Services.AddGitSmartHttp(options =>
{
    options.RepositoryRoot = "/srv/git";
    options.EnableReceivePack = true;
    options.OnReceivePackCompleted = async (context, repositoryName, updatedReferences) =>
    {
        // Log the push
        var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
        logger.LogInformation("Repository {Repository} received push updating {Count} references", 
            repositoryName, updatedReferences.Count);
        
        // Invalidate cache
        var cache = context.RequestServices.GetRequiredService<IMyRepositoryCache>();
        await cache.InvalidateAsync(repositoryName);
        
        // Trigger webhook
        foreach (var reference in updatedReferences)
        {
            logger.LogInformation("  Updated: {Reference}", reference);
        }
    };
});

Custom Repository Resolution

By default, MapGitSmartHttp expects a route with a {repository} parameter. You can customize this to use multiple parameters, no parameters (for single-repository hosting), or any custom logic:

Multiple Parameters

builder.Services.AddGitSmartHttp(options =>
{
    options.RepositoryRoot = "/srv/git";
    options.RepositoryResolver = context =>
    {
        var org = context.Request.RouteValues["organization"]?.ToString();
        var repo = context.Request.RouteValues["repository"]?.ToString();
        return string.IsNullOrEmpty(org) || string.IsNullOrEmpty(repo) 
            ? null 
            : $"{org}/{repo}";
    };
});

app.MapGitSmartHttp("/git/{organization}/{repository}.git");

Single Repository (No Parameters)

builder.Services.AddGitSmartHttp(options =>
{
    options.RepositoryRoot = "/srv/git";
    options.RepositoryResolver = context => "my-repo";
});

app.MapGitSmartHttp("/git");

From Query String or Header

builder.Services.AddGitSmartHttp(options =>
{
    options.RepositoryRoot = "/srv/git";
    options.RepositoryResolver = context =>
    {
        // Try query string first, then header
        return context.Request.Query["repo"].FirstOrDefault() 
            ?? context.Request.Headers["X-Git-Repository"].FirstOrDefault();
    };
});

app.MapGitSmartHttp("/git");

Features

• Smart HTTP compatibility for Git clients (advertise, upload-pack, receive-pack).
• SHA-1 and SHA-256 repository support through Pmad.Git.LocalRepositories.
• No dependency on the git CLI at runtime.
• Extensible authorization through user-provided callbacks.