Nodsoft.MoltenObsidian.Vaults.FileSystem 0.5.67

Molten Obsidian - Vault Providers

Premise

Molten Obsidian is designed with data source modularity in mind. As such, you'll find a plethora of Vault implementations, matching your needs.

Filesystem - Nodsoft.MoltenObsidian.Vaults.FileSystem

Description

This provider supports the classic way of loading an Obsidian vault, which is through the filesystem. By targeting a directory, you can serve a Molten Obsidian vault from it, independently of that vault being initialized through Obsidian first, or not.

Example Usage

Declare a Filesystem vault in Dependency Injection:

using Microsoft.Extensions.DependencyInjection; 

public void ConfigureServices(IServiceCollection services) 
{ 
	// Declare a FileSystem vault from path:
	services.AddMoltenObsidianFileSystemVault(new DirectoryInfo("/path/to/vault"));
	
	// Alternatively you can declare from an IServiceProvider delegate, returning a path.
	services.AddMoltenObsidianFileSystemVault(s => s.GetRequiredService<IMyService>().GetVaultDirectory());
}

Alternatively you can instantiate your own Filesystem vault like so:

using Nodsoft.MoltenObsidian.Vaults.FileSystem;

IVault vault = FileSystemVault.FromDirectory("/path/to/vault");

Known Limitations (Potential future features?)

• The FileSystem provider is readonly. This is an upstream limitation from the IVault interface itself, which does not support any write capabilities, as of now.
• No tree refresh capabilities have been implemented yet. Once instantiated, the Vault file structure is immutable.
• 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).

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

HTTP - Nodsoft.MoltenObsidian.Vaults.Http

Description

This provider supports serving a MoltenObsidian vault hosted on a remote Web server, through HTTP. 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 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 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 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. This is an upstream limitation from the IVault interface itself, which does not support any write capabilities, as of now.
• 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 any of those features are considered a necessity in your use case, feel free to voice your need by raising an issue.

FTP - Nodsoft.MoltenObsidian.Vaults.Ftp

Description

This provider supports serving a MoltenObsidian vault hosted on a remote FTP server. 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.

Example Usage

Declare an FTP vault in Dependency Injection:

using Microsoft.Extensions.DependencyInjection; 

public void ConfigureServices(IServiceCollection services) 
{
	// Add an FTP Client pointing to your remote host, along with credentials if needed,
	// Then add an FTP vault that uses that client.
	services.AddSingleton(new AsyncFtpClient("ftp.example.com", "user", "password", 21));
	services.AddMoltenObsidianFtpVault(s => s.GetRequiredService<AsyncFtpClient>());
}

Alternatively you can instantiate your own FTP vault like so:

using Nodsoft.MoltenObsidian.Vaults.Ftp;

// Instantiate the FtpClient.
// 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.
AsyncFtpClient ftpClient = new("ftp.example.com", "user", "password", 21);

// Get the vault manifest from the server.
byte[] bytes = await ftpClient.DownloadBytes("moltenobsidian.manifest.json", CancellationToken.None)   
?? throw new InvalidOperationException("Could not download manifest.");

// Instantiate the vault.
IVault vault = FtpRemoteVault.FromManifest(manifest, ftpClient);

Please note that the example path used in the above examples reflect the FTP path preceding the Manifest's moltenobsidian.manifest.json. This means the actual manifest link would be ftp://user:password@path.to/vault/moltenobsidian.manifest.json.

Known Limitations (Potential future features?)

• The FTP provider is readonly. This is an upstream limitation from the IVault interface itself, which does not support any write capabilities, as of now.
• 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 granted 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 any of those features are considered a necessity in your use case, feel free to voice your need by raising an issue.

Implementing a Vault Provider

Implementing your own vault provider is easy, provided you're familiar with the basics of file tree resolution. Indeed, depending on your data source, you'll have a different experiences implementing a provider, with the vault tree building aspect being the most daunting to all but seasoned devs.

We recommend you follow in the footsteps of the reference provider implementations, so to get a grasp of the concepts involved.

For most cases, here are a few guidelines:

• Start by implementing IVault, as this is the root of any entity connected to a vault. You'll have an easier time working your way top-to-bottom.
• We recommend you derive from a common IVaultEntity base/abstract implementation in cases where folders and files are physically represented. In remote sources, this will rarely be the case.
• We also recommend you create a Factory-style constructor (private/protected ctor & public static method) for the IVaultFile implementation. This will allow you to conditionally return a IVaultNote during construction, in case the resolved file turns out to be a Markdown file.