Developer Guide

Welcome to the Netman Developer Guide!

Here you will find a breakdown of the following items

• TLDR
• The Netman Buffer Object Life Cycle
  • How the heck does the api work?
  • What is a provider?
• How to create a provider!
  • Initial Considerations
  • Integration with api
  • Help my provider is broke!

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). There is no limit to the number of providers that Netman can have loaded at one time, Netman will only listen for events related to the protocols that the loaded providers specify they can handle. 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!

So you want to create a provider for protocol X? You've come to the right place! We are going to be creating a provider for docker, follow along!

Before we get started, ensure that you have netman installed! Head back to the README for more details on how to install netman if you have forgotten how!

Initial Considerations

Before we can begin creating our shiny new provider, we need to take a few things into consideration.

First! Have we searched for providers that might do what we are looking for on github? It could be that a provider exists to handle X protocol. If not (or you feel like making your own anyway), onto the second question

Second! What is the target program(s) of our provider? For docker, we care about the docker program. Thus, we will need to ensure that docker exists when the provider is initialized, and if it doesn't exist, we should not intialize (along with log) that we were not able to find all our dependencies. This is critical for users when they are expecting to be able to use a provider and it isn't present. The inevitable "It didn't work" can be prevented with proper error handling and communication with the user on when your dependencies aren't met.

Third! What edge cases might we run into while communicating with our program (docker in this case), and how will we handle them? It is important to know what might go wrong beforehand and ensure that we account for those scenarios, or at the very least call them out so the user has some point of reference upon errors. In docker's case, the following considerations need to be accounted for

• Docker isn't installed
  • In this case, we should simply not initialize (this is covered more below)
• The target container doesn't exist
  • In this case, we should simply reject (return nil) any requests to this container, as well as notify the user that their request is nonsensical.
• The target container isn't running
  • Here, we can handle this in one of 3 ways
    • We can die and error out that the container isn't running
    • We can prompt the user to see if we should attempt to start the container
    • We can attempt to autostart the container
• The target container doesn't have the appropriate programs installed for introspection
  • Our preferred method of traversing the file system will be to execute find within the container (much like we do in the ssh provider). This should be available on most containers but it might not be. If this is the case, we can do one of the following options
    • We can die and complain that we can't properly introspect the container
    • We can try a fallback program for introspection (such as ls)
    • We can try utilizing docker tools to externally interface with the container contents

With these considerations in mind (and valid research done), lets dive into creating our new provider!

First Steps

The first thing to do is create a new repo for our provider (docker will be included in the Netman core but for the sake of this guide, we will create a new repository)

$ git init docker-provider-netman
Initialized empty Git repository in /home/miversen/git/docker-provider-netman/.git/

There is no specific naming convention for providers, name your provider whatever you would like!

Once we have our provider repo started, lets enter the directory and create the following file structure

$ cd docker-provider-netman
$ mkdir -p lua/docker-provider-netman
$ cd lua/docker-provider-netman
$ touch init.lua

Here we are creating the basic lua file structure that neovim will be looking for when a user attempts to import our plugin. At this point, your project should look something like this

❯ ls -R docker-provider-netman 
.:
lua

./lua:
docker-provider-netman

./lua/docker-provider-netman:
init.lua

Or more clearly

> lua
    > docker-provider-netman
        > init.lua

Lets add the init.lua (in its current blank form) to the repo

$ git add init.lua

We can verify that the file has been added via

$ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   init.lua

Lets stage and commit it so we have a safe fallback when we are working!

$ git stage init.lua
$ git commit -m "Initial Filestructure"
[master (root-commit) 64aacb6] Initial Filestructure
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 lua/docker-provider-netman/init.lua

You should get something like the above. If you are having issues with working through git, atlassian provides a very helpful walkthrough of how git works and how to use it. If you are just getting started on Neovim and/or lua development, nanotree has created an excellent guide! Moving forward, we will focus on the development of the plugin and less on the stuff going on around it (meaning, there won't be more shell commands or explainations about git/shell)

To make it so that neovim will load our new provider into memory during startup, lets link our project to neovim's runtime directory

$ ln -s $HOME/git/docker-provider-netman/ $HOME/.local/share/nvim/site/pack/plugins/opt/docker-provider-netman/

Note: If you use a plugin manager, consult your plugin manager on how to load local plugins

Creating our basic provider structure

Lets create another lua file (in the same location as init.lua)

$ touch docker.lua

This is where we will put the logic for our provider!

The Netman API calls the following attributes that must be defined on every provider

• read
• write
• delete
• get_metadata
• protocol_patterns
• name
• version

It also calls out the following optional functions

• init
• close_connection

Failure to declare any of these attributes will result in the Netman api failing to import our provider! To demonstrate this, lets setup our provider to be loaded by Netman. Add the following code to your init.lua

-- init.lua
vim.g.netman_log_level = 1
local docker_provider = "docker-provider-netman.docker"
require("netman.api"):load_provider(docker_provider)

Before we can test our code, lets get the logs opened up so we can see what is happening. Netman logs can be found in $HOME/.local/share/nvim/netman/logs.txt Open a shell and tail the file

$ tail -f $HOME/.local/share/nvim/netman/logs.txt

And then from your neovim editor, run the following command

:luafile init.lua

You will be greeted with lots of errors! You can see them both in neovim

"Failed to initialize provider: docker-provider-netman.docker. This is likely due to it not being loaded into neovim correctly. Please ensure you have installed this plugin/provider"
E5113: Error while calling lua chunk: .../site/pack/packer/start/netman.nvim/lua/netman/utils.lua:242: "Failed to initialize provider: docker-provider-netman.docker. This is likely due to it not being loaded into neovim co
rrectly. Please ensure you have installed this plugin/provider"
stack traceback:
        [C]: in function 'error'
        .../site/pack/packer/start/netman.nvim/lua/netman/utils.lua:242: in function '_log'
        .../site/pack/packer/start/netman.nvim/lua/netman/utils.lua:279: in function 'error'
        ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:414: in function 'load_provider'

As well as the Netman log!

[2022-04-26 22:34:29] [SID: rwqmhmpzqjfhzne] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:412 "Attempting to import provider: docker-provider-netman.docker"  {
  status = false
}
[2022-04-26 22:34:29] [SID: rwqmhmpzqjfhzne] [Level: ERROR]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:414 "Failed to initialize provider: docker-provider-netman.docker. This is likely due to it not being loaded into neovim correctly. Please ensure you have installed this plugin/provider"

The netman logs will be critical in working through the various errors we will encounter on this journey. For more details on troubleshooting, head over to how to troubleshoot your shiny new provider

So what happened?

Why did we get the above errors? What is the code we put in init.lua doing? What to do the logs mean Mason?! Lets close neovim and review the above sections Note: Due to how lua imports packages, a close and reopen of neovim is required for each import. Work is being done to allow Netman to help alleviate this process

Lets start with the code above

-- init.lua
vim.g.netman_log_level = 1
local docker_provider = "docker-provider-netman.docker"
require("netman.api"):load_provider(docker_provider)

These 3 lines are doing the following

vim.g.netman_log_level = 1

We are setting the netman log level to level 1 (DEBUG mode). Log levels for Netman range from 1-4 (as laid out in troubleshooting steps). Setting it to 1 means we will get alot of logs which is quite helpful when we are creating a new provider! Just remember to remove this line before putting your code in production or users will have lots of logs!

local docker_provider = "docker-provider-netman.docker"
require("netman.api"):load_provider(docker_provider)

Here we are telling netman.api's load_provider function to load our new provider "docker-provider-netman.docker". When we load our provider into Netman, the string that is provided should be the same string that an end user would use to require our provider, as that is exactly what Netman does!

So now that we know what the code is doing (vaguely), what do the errors mean? The main log

"Failed to initialize provider: docker-provider-netman.docker. This is likely due to it not being loaded into neovim correctly. Please ensure you have installed this plugin/provider"

Is displayed to indicate to the user that the listed provider (docker-provider-netman.docker) is not a valid provider. This is correct, as our provider does not implement the above listed requirements to be considered a Netman compatible provider™

Lets stub these functions and variables so that we can begin development within Netman

-- init.lua
vim.g.netman_log_level = 1
local docker_provider = "docker-provider-netman.docker"
require("netman.api"):load_provider(docker_provider)

-- docker.lua
local M = {}

M.protocol_patterns = {}
M.name = 'docker'
M.version = 0.1

function M:read(uri, cache)

end

function M:write(buffer_index, uri, cache)

end

function M:delete(uri, cache)

end

function M:get_metadata(requested_metadata)

end

function M:init(config_options)

end

function M:close_connection(buffer_index, uri, cache)

end

return M

Rerunning our require

:luafile init.lua

We now don't see any errors! Success right?!

Unfortunately not. If we check the Netman logs, you will see the following lines

[2022-04-26 22:57:22] [SID: wqdzzelrxombbco] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:412 "Attempting to import provider: docker-provider-netman.docker"  {
  status = true
}
[2022-04-26 22:57:22] [SID: wqdzzelrxombbco] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:422 "Validating Provider: docker-provider-netman.docker"
[2022-04-26 22:57:22] [SID: wqdzzelrxombbco] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:433 "Validation finished"
[2022-04-26 22:57:22] [SID: wqdzzelrxombbco] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:445 "Initializing docker-provider-netman.docker:0.1"
[2022-04-26 22:57:22] [SID: wqdzzelrxombbco] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:447 "Found init function for provider!"
[2022-04-26 22:57:22] [SID: wqdzzelrxombbco] [Level: WARN]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:450 "docker-provider-netman.docker:0.1 refused to initialize. Discarding"

What gives?!

Reading through the logs, we can see a handful of things going on here. Netman did successfully import the provider, as shown by "Validation finished". However, the last line is what throws us off. Why did Netman refuse to load our provider? "docker-provider-netman.docker:0.1 refused to initialize. Discarding"

This was thrown because we created the optional init method and did not return anything from it. Thus when Netman checked to see if it can use us, we did not say yes and therefore it assumes no the docker provider is not ready to be used, and discards us. This is a safeguard in place to ensure that if a provider has initialization to perform, it is able to tell us it is indeed ready to move forward. Failure to inform Netman you are ready results in being discarded so as to not accidentally call you when you are not usable. The API Doc puts it well

Should return a true/false depending on if the provider was able to properly initialize itself

As we did not return true, initialization is considered a failure. For now, lets add a return true to the bottom of our init function in docker.lua

local M = {}

M.protocol_patterns = {}
M.name = 'docker'
M.version = 0.1

function M:read(uri, cache)

end

function M:write(buffer_index, uri, cache)

end

function M:delete(uri, cache)

end

function M:get_metadata(requested_metadata)

end

function M:init(config_options)

    return true
end

function M:close_connection(buffer_index, uri, cache)

end

return M

When we run it this time

:luafile init.lua

We will get the following output

[2022-04-26 23:06:26] [SID: uhrhnkjctoymgwt] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:422 "Validating Provider: docker-provider-netman.docker"
[2022-04-26 23:06:26] [SID: uhrhnkjctoymgwt] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:433 "Validation finished"
[2022-04-26 23:06:26] [SID: uhrhnkjctoymgwt] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:445 "Initializing docker-provider-netman.docker:0.1"
[2022-04-26 23:06:26] [SID: uhrhnkjctoymgwt] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:447 "Found init function for provider!"
[2022-04-26 23:06:26] [SID: uhrhnkjctoymgwt] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:515 "Initialized docker-provider-netman.docker successfully!"

Success! Netman accepted our provider! We are now ready to move into interfacing with Docker and the Netman API

Integration with api

Implementing Init

Reference Points

• vim.fn.jobstart
• docker
• command

So with Netman accepting our provider, we are ready to begin editing docker uris right?!

Not exactly. We are missing 2 key things before the user can utilize our provider

• We haven't defined any protocol patterns yet
• We should look back at our considerations earlier

In docker's case, the following considerations need to be accounted for

• Docker isn't installed

Addressing the first We haven't defined any protocol patterns yet, if we have not defined protocol patterns, Netman will accept our intialization but wont link protocols to our provider to consume. If you try to open a docker uri (something like docker://somecontainer/somepath), a new vim buffer will be opened for this uri, but it will be considered a file and our provider will not be called. To verify this, consider the following change to the read function in our docker.lua file

-- docker.lua
function M:read(uri, cache)
    require("netman.utils").log.debug("Loading Docker URI!")
end

Upon save and neovim reload with, try editing the above URI. You will see neovim happily open a new file called somepath and our logs do not show any attempt to reach the docker provider we gave it!

So what happened? Why did our provider not get called like we expected? During the load_provider call we do in init, Netman is reading the contents of our protocol_patterns array. Which, as we declared above, is completely empty

-- docker.lua
M.protocol_patterns = {}

Thus, while Netman did accept our provider, it did not register any protocols to us. To fix that, lets get a pattern added to our protocol patterns

-- docker.lua
M.protocol_patterns = {'docker'}

Note: As called out in the API Documentation, do not use a glob for the protocol handler here. Simply list the protocol you are interested in, Netman will handle creating the proper glob for it

protocol_patterns should be an array of the various protocols (not blobs) that the provider supports.

If we reload Neovim again we will now see the following log

[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:412 "Attempting to import provider: docker-provider-netman.docker"  {
  status = true
}
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:422 "Validating Provider: docker-provider-netman.docker"
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:433 "Validation finished"
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:445 "Initializing docker-provider-netman.docker:0.1"
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:447 "Found init function for provider!"
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:462 "Reducing docker down to docker"
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:507 "Augroup Netman already exists, not recreating augroup"
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:510 'Setting Autocommand: autocmd Netman FileReadCmd docker://* lua require("netman"):read(vim.fn.expand("<amatch>"))'
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:510 'Setting Autocommand: autocmd Netman BufReadCmd docker://* lua require("netman"):read(vim.fn.expand("<amatch>"))'
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:510 'Setting Autocommand: autocmd Netman FileWriteCmd docker://* lua require("netman"):write()'
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:510 'Setting Autocommand: autocmd Netman BufWriteCmd docker://* lua require("netman"):write()'
[2022-04-26 23:24:19] [SID: yoactdtovslrwdu] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:510 'Setting Autocommand: autocmd Netman BufUnload docker://* lua require("netman.api"):unload(vim.fn.expand("<abuf>"))'
[2022-04-26 23:24:20] [SID: yoactdtovslrwdu] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:515 "Initialized docker-provider-netman.docker successfully!"

Here we can see the usual logs we saw earlier about intialization, but there are new logs being output now! Logs about connecting docker://* to Netman!

If we try to edit the above docker://somecontainer/somepath

:edit docker://somecontainer/somepath

we will see the following logs

[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: WARN]   -- ...m/site/pack/packer/start/netman.nvim/lua/netman/init.lua:12  "Fetching file: docker://somecontainer/somepath"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:173 "No cache table found for index: 1. Creating one now"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:177 "No cache object associated with protocol: docker for index: 1. Attempting to claim one"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:84  "Selecting provider: docker-provider-netman.docker:0.1 for path: docker://somecontainer/somepath"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:137 "Reaching out to provider: docker-provider-netman.docker:0.1 to initialize connection for path: docker://somecontainer/somepath"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:150 "Cached provider: docker-provider-netman.docker:0.1 for id: ypqjtahgej"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:188 "Claiming ypqjtahgej and associating it with index: 1"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:211 "Claimed ypqjtahgej and associated it with 1"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:214 "Removed unclaimed details for ypqjtahgej"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...er-provider-netman/lua/docker-provider-netman/docker.lua:8   "Loading Docker URI!"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:303 "Setting read type to api.READ_TYPE.STREAM"
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG]  -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:304 "back in my day we didn't have optional return values..."
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: INFO]   -- ...im/site/pack/packer/start/netman.nvim/lua/netman/api.lua:313 "Received nothing to display to the user, this seems wrong but I just do what I'm told..."
[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: WARN]   -- ...m/site/pack/packer/start/netman.nvim/lua/netman/init.lua:15  "No command returned for read of docker://somecontainer/somepath"

[2022-04-26 23:26:32] [SID: htsmyzufhpjsgkd] [Level: DEBUG] -- ...er-provider-netman/lua/docker-provider-netman/docker.lua:8 "Loading Docker URI!"

Success! We can now see that our read function was called

However, we still have our second point to handle.

We should look back at our considerations earlier . In docker's case, the following considerations need to be accounted for

• Docker isn't installed

We haven't checked to ensure that our provider can actually be useful to the end user, so lets do that!

In our case, we simply need to ensure that the docker command is available on our path (and that the user can execute it).

Lets look at how we might check if the docker command is available and usable outside the Netman framework.

If docker exists, using the command shell function will give us the following output

$ command -v docker; echo $?
/usr/bin/docker
0

Note: echo $? is printing out the exit code from command. 0 is a success here

If docker doesn't exist, the function will give us the following output

$ command -v docker; echo $?
1

Notice that here we do not get any STDOUT from the command, and the exit code is 1? This means that docker is not available on the path. This is a great way for us to check if docker is installed, we can execute the above line and consume STDOUT.

Great! So we have a command we can run, lets get that put in our init function!

function M:init(config_options)
    local command = 'command -v docker' -- command we are going to run as discussed above
    local stdout = {} -- empty table to capture standard output from vim.fn.jobstart
    local stderr = {} -- empty table to capture standard error from vim.fn.jobstart
    vim.fn.jobwait({vim.fn.jobstart(command, {
        on_stdout = function(job_id, output) for _, line in ipairs(output) do table.insert(stdout, line) end end,
        on_stderr = function(job_id, output) for _, line in ipairs(output) do table.insert(stderr, line) end end
    })}) -- Run job, capture output from standard out and standard error, and wait for job to finish
    local error = table.concat(stderr, '') -- Merge stderr into a string
    local docker_path = table.concat(stdout, '') -- Merge stdout into a string
    if error ~= '' or docker_path == '' then -- If we got an error or _didn't_ get stdout, we need to fail
        require("netman.utils").notify.error("Unable to verify docker is available to run!")
        if error ~= '' then require("netman.utils").log.warn("Found error during check for docker: " .. error) end
        if docker_path == '' then require("netman.utils").log.warn("Docker was not found on path!") end
        return false
    end
    -- Success!
    require("netman.utils").log.info("Docker found at '" .. docker_path .. "'!")
    return true
end

The above is certainly a mouthful. It is worth looking at alternative tools for command interfacing such as netman.utils or the fantastic plenary.nvim

Below is a cleaned up way of doing this with the provided tools in netman.utils

function M:init(config_options)
    local command = 'command -v docker'
    local command_flags = require("netman.options").utils.command
    local command_options = {}
    command_options[command_flags.IGNORE_WHITESPACE_ERROR_LINES] = true
    command_options[command_flags.IGNORE_WHITESPACE_OUTPUT_LINES] = true
    command_options[command_flags.STDERR_JOIN] = ''
    command_options[command_flags.STDOUT_JOIN] = ''
    local command_output = require("netman.utils").run_shell_command(command, command_options)
    local docker_path, error = command_output.stdout, command_output.stderr
    if error ~= '' or docker_path == '' then
        require("netman.utils").notify.error("Unable to verify docker is available to run!")
        if error ~= '' then require("netman.utils").log.warn("Found error during check for docker: " .. error) end
        if docker_path == '' then require("netman.utils").log.warn("Docker was not found on path!") end
        return false
    end
    require("netman.utils").log.info("Docker found at '" .. docker_path .. "'!")
    return true
end

With the above in place, we can now safely assume that if Netman is interfacing with us, our dependencies are available for us. It is also worth logging out relevant information for future use. Below is the finished product of the init function

-- docker.lua
local log = require("netman.utils").log
local notify = require("netman.utils").notify
local shell = require("netman.utils").run_shell_command
local command_flags = require("netman.options").utils.command
-- Rest of file
function M:init(config_options)
    local command = 'command -v docker'
    local command_options = {}
    command_options[command_flags.IGNORE_WHITESPACE_ERROR_LINES] = true
    command_options[command_flags.IGNORE_WHITESPACE_OUTPUT_LINES] = true
    command_options[command_flags.STDERR_JOIN] = ''
    command_options[command_flags.STDOUT_JOIN] = ''
    local command_output = shell(command, command_options)
    local docker_path, error = command_output.stdout, command_output.stderr
    if error ~= '' or docker_path == '' then
        notify.error("Unable to verify docker is available to run!")
        if error ~= '' then log.warn("Found error during check for docker: " .. error) end
        if docker_path == '' then log.warn("Docker was not found on path!") end
        return false
    end
    local docker_version_command = "docker -v"
    command_output = shell(docker_version_command, command_options)
    if command_output.stderr ~= '' or command_output.stdout == '' then
        notify.error("Invalid docker version information found!")
        log.info("Received Docker Version Error: " .. command_output.stderr)
        return false
    end
    log.info("Docker path: '" .. docker_path .. "' -- Version Info: " .. command_output.stdout)
    return true
end

Implementing Read

How to troubleshoot your shiny new provider