Implemented ProviderConnect Spec

[miversen33]

I am trying something new with spec changes. Please let me know your thoughts (to the ghosts of the machine most likely) on this format for spec changes. Note, I am thinking of doing this kind of spec write up/documentation for Spec Changes only (as it is quite intensive).

Below is the spec this PR is aiming to implement

---

Provider host connection management proposal

Related Issues:

• Probably should break apart the "connection" and "processing" parts of the SSH provider #148
• Support distant:// scheme? #150

Abstraction

To better accommodate more complex providers (such as SSH, distant, rsync, etc), we should consider creating a
way to both indicate to the provider that a connection event has been requested as well as indicate that a disconnection
event has been requested. Additionally, a provider should be given a way to inform the API if a URI Host is currently
connected or not. Lastly, moving in line with #117 , all connection and disconnection processing should have an optional (recommended though) asynchronous counterpart.

Implementation

API

The facilitate communication to abstracted providers from consumers, it would make sense to have all connection/disconnection
events be processed via the exposed Netman API. This means the following functions would need to be created within the API

• api.connect_to_uri_host
• api.disconnect_from_uri_host
• api.has_connection_to_uri_host

Additionally, 2 new netman events need to be created

• netman_provider_host_connect
• netman_provider_host_disconnect

Below is the proposed signatures for the above functions

connect_to_uri_host

--- Attempts to execute a connection event on the underlying
--- provider for the provided URI. Note, successful
--- connection to the URI host (per the provider) will trigger
--- a `netman_provider_host_connect` event
--- @param uri: string
---     The string URI to connect to
--- @param callback: function | Optional
---     If provided, indicates that the connection event
---     should be asynchronous if possible.
---     NOTE: Even if it is impossible to asynchronously execute
---     the connection, the response will still be provided
---     via the callback as that is what is expected by the end user
--- @return table | boolean
---     If an error is encountered while trying to execute the
---     connection event, a table will be returned with the following structure
---     {
---         message: string,
---         -- Whatever the message is,
---         process: function | Optional,
---         -- If this is provided, call this function with whatever
---         -- response the user provides to the message that was provided
---         is_error: boolean | Optional
---         -- If provided, indicates that the message is an error
---     }
---     
---     If the requested connection event is synchronous, this will
---     simply return the boolean (T/F) response from the provider
---     after completing the connection request
---     
---     If the requested connection event was asynchronous, this will
---     return a table that contains the following key/value pairs
---     {
---         read: function,
---         -- Takes an optional string parameter that can be
---         -- "STDERR", or "STDOUT" to indicate which pipe to read from.
---         -- Defaults to "STDOUT"
---         write: function,
---         -- Takes a string or table of data to write to the
---         -- underlying handle
---         stop: function
---         -- Takes an optional boolean to indicate the stop should
---         -- be forced
---     }
function M.connect_to_uri_host(uri, callback)

end

disconnect_from_uri_host

--- Attempts to execute a disconnection event on the underlying
--- provider for the provided URI. Note, successful
--- disconnection from the URI host (per the provider) will trigger
--- a `netman_provider_host_disconnect` event
--- @param uri: string
---     The string URI to disconnect from
--- @param callback: function | Optional
---     If provided, indicates that the disconnection event
---     should be asynchronous if possible.
---     NOTE: Even if it is impossible to asynchronously execute
---     the disconnection, the response will still be provided
---     via the callback as that is what is expected by the end user
--- @return table | boolean
---     If an error is encountered while trying to execute the
---     disconnection event, a table will be returned with the following structure
---     {
---         message: string,
---         -- Whatever the message is,
---         process: function | Optional,
---         -- If this is provided, call this function with whatever
---         -- response the user provides to the message that was provided
---         is_error: boolean | Optional
---         -- If provided, indicates that the message is an error
---     }
---     
---     If the requested disconnection event is synchronous, this will
---     simply return the boolean (T/F) response from the provider
---     after completing the disconnection request
---     
---     If the requested disconnection event was asynchronous, this will
---     return a table that contains the following key/value pairs
---     {
---         read: function,
---         -- Takes an optional string parameter that can be
---         -- "STDERR", or "STDOUT" to indicate which pipe to read from.
---         -- Defaults to "STDOUT"
---         write: function,
---         -- Takes a string or table of data to write to the
---         -- underlying handle
---         stop: function
---         -- Takes an optional boolean to indicate the stop should
---         -- be forced
---     }
function M.disconnect_from_uri_host(uri, callback)

end

has_connection_to_uri_host

--- Attempts to reach out to the provider
--- to verify if the URI has a connected host
--- @param uri: string
---     The string URI to check
--- @return boolean
---     Will return True if (and only if) the provider
---     explicitly informed us that the URI was connected.
---     Failure to connect to the provider for this check,
---     or a false response from the provider will both return
---     false on this call
function M.has_connection_to_uri_host(uri)

end

Provider

In order for the API to leverage these connection events, a provider will need to
implement the following functions.

In order to support asynchronous events, an additional (recommended)
_a variant of the connect_host and close_host functions can be implemented

NOTE: These functions are optional, though if they are not implemented, the
API will not be able to leverage connection events and information for any protocols
that the provider supports.

• provider.connect_host
• provider.connect_host_a
• provider.is_connected
• provider.close_host
• provider.close_host_a

Below is the proposed signatures for the above functions

connect_host

--- Synchronously connect to the host of the provided URI
--- @param uri: string
---     The string form of the URI to connect to.
---     It is expected that you can extract the host from
---     this URI
--- @param cache: netman.tools.Cache
---     A cache object that is provided to any function
---     within the provider.
--- @return boolean
---     Return true/false on if the connection event was successful or not
function M.connect_host(uri, cache)

end

connect_host_a

--- Asynchronously connect to the host of the provided URI
--- @param uri: string
---     The string form of the URI to connect to.
---     It is expected that you can extract the host from
---     this URI
--- @param cache: netman.tools.Cache
---     A cache object that is provided to any function
---     within the provider.
--- @param exit_callback: function
---     The function to call when connection has been completed.
---     This function should be called with a simple `true/false`.
---     If there was an error of some kind that needs addressing,
---     a table in the following form can be provided instead
---     {
---         message: string,
---         -- The message to inform the user about
---         process: function,
---         -- A function to call if the message should be used
---         -- as input for something.
---         is_error: boolean | Optional
---         -- If provided, indicates that the message is an error
---     }
--- @return netman.tools.shell.handle
---     This should be a shell handle as created by `netman.tools.shell.new_async_handler`
---     or `netman.tools.shell.run`
function M.connect_host_a(uri, cache, exit_callback)

end

is_connected

--- Verifies if we currently have a connection to the host
--- of the provided URI
--- @param uri: string
---     The string form of the URI to connect to.
---     It is expected that you can extract the host from
---     this URI
--- @param cache: netman.tools.Cache
---     A cache object that is provided to any function
---     within the provider.
--- @return boolean
---     Return a true/false to indicate if there
---     is a connection. Note, this should be _fast_ (as in free).
---     **DO NOT DO EXPENSIVE CHECKS FOR CONNECTION HERE.
---     USE THE CACHE TO STORE THAT KIND OF INFORMATION FOR EASY RETRIEVAL**
function M.is_connected(uri, cache)

end

close_host

--- Synchronously disconnect from the host of the provided URI
--- @param uri: string
---     The string form of the URI to connect to.
---     It is expected that you can extract the host from
---     this URI
--- @param cache: netman.tools.Cache
---     A cache object that is provided to any function
---     within the provider.
--- @return boolean
---     Return true/false on if the disconnection event was successful or not
function M.close_host(uri, cache)

end

close_host_a

--- Asynchronously disconnect from the host of the provided URI
--- @param uri: string
---     The string form of the URI to connect to.
---     It is expected that you can extract the host from
---     this URI
--- @param cache: netman.tools.Cache
---     A cache object that is provided to any function
---     within the provider.
--- @param exit_callback: function
---     The function to call when disconnection has been completed.
---     This function should be called with a simple `true/false`.
---     If there was an error of some kind that needs addressing,
---     a table in the following form can be provided instead
---     {
---         message: string,
---         -- The message to inform the user about
---         process: function,
---         -- A function to call if the message should be used
---         -- as input for something.
---         is_error: boolean | Optional
---         -- If provided, indicates that the message is an error
---     }
--- @return netman.tools.shell.handle
---     This should be a shell handle as created by `netman.tools.shell.new_async_handler`
---     or `netman.tools.shell.run`
function M.close_host_a(uri, cache, exit_callback)

end

[miversen33]

I'm merging this in so I can continue working on the async process. If shenanigans happen, I can drop this commit and pretend like nothing happened 🙃