Skip to content

Developer Guide

Jump to bottom
Mike Iversen edited this page Apr 27, 2022 · 33 revisions

Welcome to the Netman Developer Guide!

Here you will find a breakdown of the following items

TLDR

The Netman Buffer Object Life Cycle

The "Netman Buffer Object" is the object that api creates to help keep track of data associated with a neovim buffer. This is automatically created by the api when neovim creates a buffer (via the FileReadCmd, or BufReadCmd). This object is only created for buffers where the file uri being opened is associated with a provider.

But how does api associate a uri with a provider?

Netman is a clever little program, it only pays attention to buffer open events based on the file name (as neovim considers it). Netman selectively creates event listeners specifically for protocols as registered by providers. This means that if you have a provider loaded for ssh

spoiler alert you do if you are using Netman
and no other providers, Netman will only listen to files opened that start with ssh related protocols (as defined by the ssh provider). These events listeners (called autocommands in vim speak) are all cleanly housed in the Netman command group (called augroup in vim speak).

Netman will use this object to track internal metadata about the uri (its provider, if it has a local file stored somewhere, what buffer its on, a provider cache, etc). This is to help prevent Netman from having to redo logic when seeing a uri that is has already processed. Additionally, this buffer object contains a provider specific cache that is passed to the provider on most function calls so the provider can safely store "relevant" information to the uri.

Ok thats cool but what about when the user is done with the file?

Netman has its greedy little hooks into a handful of places in neovim's event system, one of those places being the BufUnload event. When neovim fires this event on a buffer that Netman is watching, Netman will receive the event and proceed to clear out the object from its memory. Additionally, if the provider associated with the buffer has implemented the close_connection function, Netman will call out to it to inform it that the buffer for the uri was closed.

Sounds pretty cool, but

How the heck does the api work?

The api is the main "guts" of Netman. It sits between neovim (and therefore the end user) and the provider. Both of them communicate with it via a standard set of functions, and this allows the api to communicate "between" them in an abstract way (so the end user doesn't have to care how to interface with a protocol and the provider doesn't have to care about how to interface with a user).

Sounds cool but why would a user talk to Netman instead of neovim?

The best part of all of this is that Netman's api cleanly integrates itself into neovim and thus the user (and neovim) don't have to care about how to talk to it. The user will simply utilize neovim as they would regularly do, except Netman provides additional functionality to interface with remote data via the provider structure. When a user opens a remote location (via uri), Netman will take over and ensure a clean experience between the user and the provider.

How does Netman do that?

Netman has the following events set for providers that are registered with it

  • FileReadCmd
    • This autocommand is used to capture when neovim is opening a file with a protocol that Netman supports.
  • BufReadCmd
    • This autocommand is used to capture when neovim is opening a buffer with a protocol that Netman supports.
  • FileWriteCmd
    • This autocommand is used to capture when the user is writing out to a file (before the write occurs) for a buffer that Netman is watching.
  • BufWriteCmd
    • This autocommand is used to capture when the user is writing out their buffer (before the write occurs), when the buffer is one that Netman is watching
  • BufUnload
    • This autocommand is used to capture when a relevant buffer is being closed by the user. Netman will reach out to the associated provider to inform it that the buffer is being closed

When a ReadCmd event is fired, Netman forwards the associated uri to its read command, where the api establishes which provider should handle the read, and then provides the results from the provider to the user. This is laid out more in the api documentation

Additionally, Netman does expose a vim command :Nmread which directs to the read api. This can be used by the user but is more meant for you the developer.

When a WriteCmd event is fired, Netman forwards the associated uri to its write command, where the api grabs the cached provider and informs it that the user wishes to write out their buffer to this uri. More details on how write works is explained in the api documentation

Additionally, Netman does expose a vim command :Nmwrite which directs to the write api. This can be used by the user but is more meant for you the developer.

There is alot of talk about providers

What is a provider?

A provider is a program that sits between Netman and an external data source that is not reachable in "traditional" means. An example of a provider is the builtin ssh provider, netman.providers.ssh. In this case, the ssh provider sits between Netman and ssh related programs (ssh, sftp, scp), and since it has implemented the required provider interface, api is able to safely assume that it can be communicated with to gather information from the various ssh related programs when a user requests to do so (with a uri, such as sftp://myhost/my/super/secret/file).

A provider should return consistent data (as declared in the api documentation), though it does not have to store anything within the local filesystem.

That sounds pretty cool but Netman doesn't support X protocol.

How to create a provider!

Initial Considerations

Integration with api

How to troubleshoot your shiny new provider

Clone this wiki locally