HTTP / HTTPS Vault Provider

NuGet Package : Nodsoft.MoltenObsidian.Vaults.Http

Description

This provider supports serving a MoltenObsidian vault hosted on a remote Web server, through HTTP or HTTPS. By targeting a Vault manifest file (generated by the CLI Tool), you can serve a Molten Obsidian over the wire, which is considered out of bounds of the reference Obsidian implementation.

Applications for this provider vary greatly, as you can now host your Molten Obsidian repository on several platforms :

• Self-hosted: Host your vault on a separate web server, served using Apache or Nginx.
• GitHub: Host your vault in a git repository with the manifest, and serve it over the Blob APIs.
• Azure: Store your vault in a storage (blob/file) account, and serve it over the Web/DL APIs.

Relying on the Vault Manifest allows for the vault elements to only be downloaded/streamed on a need basis, instead of prematurely transferring a vault of potentially significant size over the wire. This comes at a cost of immutability, until the manifest is updated.

Example Usage

Declare an HTTP/HTTPS vault in Dependency Injection:

using Microsoft.Extensions.DependencyInjection; 

public void ConfigureServices(IServiceCollection services) 
{
	// Declare a HTTP vault from Web root path.
	// This will internally declare and use its own HttpClient. You'll usually avoid this in production-grade scenarions.
	services.AddMoltenObsidianHttpVault(new DirectoryInfo("https://path.to/vault"));
	
	// Alternatively you can declare from an IServiceProvider delegate, returning a HttpClient.
	// This use case is usually coupled with the use of an IHttpClientFactory to manage the lifetime of the client.
	services.AddHttpClient("MoltenObsidian", client => client.BaseAddress = new("https://path.to/vault"));
	services.AddMoltenObsidianHttpVault(s => s.GetRequiredService<IHttpClientFactory>().CreateClient("MoltenObsidian"));
}

Alternatively you can instantiate your own HTTP/HTTPS vault like so:

using Nodsoft.MoltenObsidian.Vaults.Http;

// Instantiate the HttpClient.
// Please note that the client's lifetime must follow that of the Vault itself, 
// as it will be reused for retrieving the vault's contents on-demand.
HttpClient httpClient = new() { BaseAddress = new("https://path.to/vault") };

// Get the vault manifest from the server.
RemoteVaultManifest manifest = await httpClient.GetFromJsonAsync<RemoteVaultManifest>("moltenobsidian.manifest.json") 
	?? throw new InvalidOperationException("Failed to retrieve the vault manifest from the server.");

// Instantiate the vault.
IVault vault = HttpRemoteVault.FromManifest(manifest, httpClient);

Please note that the example path used in the above examples reflect the HTTP/HTTPS path preceding the Manifest's moltenobsidian.manifest.json. This means the actual manifest link would be https://path.to/vault/moltenobsidian.manifest.json.

Known Limitations (Potential future features?)

• The HTTP provider is readonly by constraint.
• No tree refresh capabilities have been implemented yet. Once instantiated, the Vault file structure is immutable. This is by constraint, as we'd need to design a refresh mechanism on the vault's manifest itself ; The implications of which are debatable.
• No caching support on the provider itself. This is both by design and by constraint, as we intend to keep the reference Vault implementations as unopinionated as possible, relying on the most minimal set of dependencies (exception noted for MS-DI/MEDI, which is taken for ganted as a standard for DI).
• No checksum comparison implementation. While the Manifest holds the checksum of each file, there is currently no use for these as of yet. If you use a custom HTTP implementation on .NET (or have changed default HttpClient config which is known good) and don't require transport security, this can cause a security issue, as the provider may in worst cases serve tampered files over the wire.

If any of those features are considered a necessity in your use case, feel free to voice your need by raising an issue.