dotnet add package Elefess --version 1.2.0
NuGet\Install-Package Elefess -Version 1.2.0
<PackageReference Include="Elefess" Version="1.2.0" />
paket add Elefess --version 1.2.0
#r "nuget: Elefess, 1.2.0"
// Install Elefess as a Cake Addin #addin nuget:?package=Elefess&version=1.2.0 // Install Elefess as a Cake Tool #tool nuget:?package=Elefess&version=1.2.0
Elefess is a Git LFS server implementation following the API spec, allowing for the design and usage of fully custom Git LFS servers beyond those provided by popular Git hosts such as GitHub or GitLab.
Elefess on its own does not function as a Git LFS server out of the box. You will need a hosting setup such as Elefess.Hosting.AspNetCore or your own hosting solution to run a server. This project contains the core interfaces (+ a few implementations) and the API JSON models.
Elefess core types
- All official Elefess hosting implementation types will access and execute its appropriate types and methods in the following order - Custom or third-party implementations are certainly not required or expected to follow it strictly, but it is recommended to do so for consistency.
- Elefess utilizes an
Exception-based approach for its request execution pipeline to avoid boilerplate code or heavy reliance on third-party libraries. In lieu of a
Result-based approach, implementations of Elefess' various interface types should be expected to throw the appropriate
Exceptionin an error state, instead of returning an error value or string directly.
- All types which are required in the execution pipeline in first-party hosting solutions will be suffixed with an asterisk (*).
1. ILfsAuthenticator *
The Git LFS API uses HTTP Basic Authentication to authorize requests. First in the request pipeline, an instance of
ILfsAuthenticator is designed to authenticate a request from the (base64) decoded credentials supplied:
Task AuthenticateAsync(string id, string password, LfsOperation operation, CancellationToken cancellationToken);
In an example request with the
Authorization header value of
Basic ZWxlZmVzczpzZWNyZXQx, Elefess will decode and split this into an
elefess, and a
secret1, which will be passed into the
AuthenticateAsync method above.
Implementations can utilize the
operation parameter to determine, for example, whether the requesting client has appropriate read or write access to the file they are trying to upload or download.
Current Elefess implementations include support for GitHub, with more planned for the future.
While not strictly a part of the Git LFS API spec, a server may find it desirable or necessary to arbitrarily validate and deny requests depending on what data is provided in the request body:
Task ValidateAsync(LfsBatchTransferRequest request);
Registering your own instance of
ILfsRequestValidator is not required for any first-party hosting solutions, but if one is created and registered where appropriate, it will be executed.
3. ILfsTransferSelector *
In the event that a client and server support different, custom, or newer Batch API transfer adapters other than the
basic transfer adapter, an implementation of
ILfsTransferSelector can be used for this purpose:
Task<LfsTransferAdapter> SelectTransferAsync(ICollection<LfsTransferAdapter> requestedTransferAdapters, CancellationToken cancellationToken);
A request can include an array of transfer adapter names - or if none are specified, the server should assume the client supports and is asking for the
basic transfer adapter. A default implementation, BasicLfsTransferRequestSelector, which will automatically select the
basic transfer adapter so long as the client supports it, is provided with Elefess.
4. ILfsObjectManager * and ILfsOidMapper
Once a request has been authenticated, and the request has been validated (when appropriate), an Elefess server will then convert request objects to response objects via an implementation of
Task<IReadOnlyCollection<LfsResponseObject>> CreateObjectsAsync(IList<LfsRequestObject> objects, LfsOperation operation, CancellationToken cancellationToken);
A default implementation, DefaultLfsObjectManager, is provided with Elefess, and simply converts request objects into response objects by passing each object into an implementation of
Task<LfsResponseObject> MapObjectAsync(string oid, long size, LfsOperation operation, CancellationToken cancellationToken);
An Elefess server implementing this interface would then be able to convert into an appropriate response object depending on the input data. For example:
- If a request is to upload OID
374252189, the server would return
LfsResponseObject.BasicUpload(new($"https://example.com/upload/a0dca55d00d4e444d87326146a721ce41d494783ea9a0fdf7e2826a32a8bbc24")), which would be converted to an
uploadaction to POST to the
- If a request is to download OID
476885649, if there is no file corresponding to that OID, the server would return
LfsResponseObject.FromError(LfsObjectError.NotFound()), which would be converted to an
errorobject indicating that the specified object could not be found.
- If the
DefaultLfsObjectManageris utilized, an implementation of
ILfsOidMapperis required. In the case of a different implementation being used, it is not necessarily required but can still be utilized in the manner detailed above.
|Product||Versions Compatible and additional computed target framework versions.|
|.NET||net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed.|
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Elefess:
Elefess.Authenticators.GitHub is a custom ILfsAuthenticator implementation for Elefess which utilizes a GitHub username & personal access token for Basic authorization.
Elefess.Hosting.AspNetCore is a custom host implementation for Elefess which utilizes ASP.NET Core Minimal APIs to host an Elefess server.
This package is not used by any popular GitHub repositories.
Split READMEs into per-project files.