sshare/README.md

# SSHare

Upload files to a server via ssh

## Installing

SSHare is not available on [PyPI](https://pypi.org).
To install it you will need to clone the repo and use pip to install it
```
git clone https://forge.monodon.me/Gnarwhal/sshare.git
cd sshare
pip install ./
```

By default, the only dependency SSHare has is the system's `ssh` (and `scp`) commands.
Beyond that it only utilises the python standard library.

### Additional Functionality

The base install is fairly bare bones in terms of functionality.
Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there is a sampling of
plugins which provide some additional conveniences

Refer to the above documentation for information on installing plugins

## Documentation - End User

Getting started with SSHare is about getting familiar with configuring SSHare.
SSHare configuration is all done in the `${XDG_CONFIG_DIR}/sshare` if set, or in `~/.config/sshare` otherwise.
In this directory are two important items: the `config.toml` file and the `plugins/` directory.

### `plugins/`

The `plugins/` directory is home to all external plugins. Installing a plugin is as simple as saving the
the plugin's `.py` file to the `plugins/`.

### `config.toml`

The configuration file can be broken down into three major components: `spec`, `config`, and `flags`.

#### `spec`

```toml

[spec.default]
name = [ "time", "extension" ]

[spec.example]
flag = { short = "e", long = "example" }
name = [ "preserve", "extension" ]

[spec.noshort]
flag = { long = "only" }
name = [ "time" ]
help = "No short flag, only long flag >:("
```

The `spec` section is a collection of different runtime specifications. The name of a specification is
unimportant with the exception of `default`, which is run when no other spec is activated. In each specification
that isn't `default`, there is a `flag` attribute that sets which command line arguments activate the
specification. The `flag` attribute must have one or both of `short` or `long`, where `short` will be set the flag
`-{short}` and `long` will set the flag `--{long}`. The `name` attribute of a specification is an array of name type
plugins which controls the order in which said plugins are executed. Specifications can also provide a brief description
in the `help` attribute, which will be displayed when `sshare --help` is run. In the example above,
running `sshare --help` would give
```
options:
  -e, --example         Use example spec
  --only                No short flag, only long flag >:(
```
#### `config`

```toml
[config.ssh]
host = "example.com"
path = "/directory/to/store/files/in"
port = 22
```

The `config` section is used to set configuration options for plugins. Refer to documentation for a plugin to see
what options can be set here. Documentation for default plugins is included [below](#Default-Plugins).

#### `flags`

```toml
[flags.file]
file = { short = "f" }

[flags.stdin]
stdin = { short = "" }

[flags.example]
option = { short = "o", long = "ooooption" }
```

The `flags` section is used to bind plugin arguments to a command line argument. They are specified in the same way
as the `flag` option for `spec`s. If `long` is left unspecified, the long flag will be set to the default provided by
the plugin. In the example above, running `sshare --help` would give:
```
options:
  -f file, --file file  Upload a file
  -, --stdin            Upload from stdin
  -o xmpl, --ooooption xmpl
                        This is not a real plugin that exists
```

### Default Plugins

#### `command_line`

A `logger` plugin which prints to the command line. No configuration needed.

#### `extension`

A `name` plugin which appends the source type to the end of the file name (i.e. `txt`, `png`, etc...). No configuration needed.

#### `file`

A `source` plugin which provides a file to be uploaded. File is specified with the `--file {file_path}` argument. No configuration needed.

#### `preserve`

A `name` plugin which preserves the name of the source in the uploaded file. No configuration needed.

#### `print_location`

A `feedback` plugin which prints the location that sources can be accessed from. No configuration needed.

#### `ssh`

An `upload` plugin which uploads the sources to the server using `ssh`.

##### Configuration
| Attribute | Type   | Default | Description                                          |
|-----------|--------|---------|------------------------------------------------------|
| host      | string | None    | The hostname to ssh into                             |
| path      | string | None    | The path of the directory to upload the sources into |
| port      | int    | 22      | The port to ssh into                                 |
| user      | string | $USER   | The user to ssh as                                   |

#### `stdin`

A `source` plugin which reads from stdin. No configuration needed.

#### `time`

A `name` plugin which adds the current unix time to the name of the of the uploaded file.

##### Configuration
| Attribute | Type   | Default | Description                                          |
|-----------|--------|---------|------------------------------------------------------|
| format    | int    | 62      | The base between 2 and 62 to represent the number in |

##### `uri`

A `location` plugin which constructs the resulting URI that the uploaded file can be accessed from.

##### Configuration
| Attribute | Type   | Default | Description                                          |
|-----------|--------|---------|------------------------------------------------------|
| protocol  | string | https   | The protocol of the URI                              |
| host      | string | None    | The hostname the file can be accessed from           |
| port      | int    | 22      | The port the file can be accessed at                 |
| path      | string | None    | The path the file can be accessed at                 |

## Documentation - Plugin Development

A plugin for SSHare is just a python file (`*.py`). There are currently 6 types of plugins:
- `logger`
- `source`
- `name`
- `upload`
- `location`
- `feedback`
A plugin can specify be any combination of the above types. For examples of plugins see [here](src/sshare/plugins)
and [here](https://forge.monodon.me/Gnarwhal/sshare_plugins)

### General Attributes

Every plugin regardless of type specifies or is provided with these attributes.

#### `plugin_type`

This mandatory paramater specifies what type(s) this plugin is.
It can be either a:
- `string` - Promotes to `{ string }`
- `set` - A set containing each of the plugin's types. 

#### `activate`

This optional parameter specifies what flag(s) or argument(s) must be passed for this plugin to be activated.
It can be either a:
- `string` - Promotes to `{ string }`
- `set` - Promotes to `{ plugin_type: { string, ... }, plugin_type2: { string, ... }, ... }`
- `dict` - A dictionary that maps each type the plugin is, to the flags or arguments that activate the plugin for that type
All arguments specified in `activate` must be provided by the user for the plugin to activate. 

#### `config`

This optional parameter specifies configuration options for the plugin. These values are what a user is allowed to change
through `config.toml`. It is a map containing `{ option: default_value, ... }`. If there is no default value (i.e. it is mandatory
that the user set it explicitly) for the option, it can be set to `NoDefault` provided by
`from sshare.plugin.config import NoDefault`.  
  
While `config` is initially specified as a `dict`, when the plugin is loaded it will be converted to an object with attributes.
For example, if a config is specified as 
```python
config = {
    "example0": 42,
}
```
it would then be accessed by `config.example` not `config["example"]`.

#### `args`

This optional parameter specifies arguments for the plugin. These values are also accessed from the `config` object,
however they are provided via program arguments as opposed to being specified in `config.toml`. An option specified
in both `config` and `args` will be loaded from the config file first and overriden by the program argument if
provided. Arguments are of type `Argument` provided by `from sshare.plugin.config import Argument`.
`Argument` takes `name` (optionally) and a list of `kwargs` equivalent to the option document [here](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_argument). As a convenience there is also `Flag` provided by
`from sshare.plugin.config import Flag`, which is for boolean arguments which take no parameters.
`Flag` only takes a `help=...` paramater.

#### `init`

If a plugin needs to do any initialisation, it can be done in the `init` method. The `init` method takes no parameters
and returns no values.

#### `logger`

Logger is not specified by the plugin developer, but is available inside the plugin if needed. The logger
has three levels: `info`, `warn` and `error`.

### Type Specific Attributes

#### `logger`
- `info(str)`
- `warn(str)`
- `error(str)`

#### `source` -> `get_source()`

The `get_source` function takes no arguments and returns a source. There are currently two types of sources provided by
`from sshare.plugin.source import (Raw | File)`.
- `Raw` - A raw data source. It has a type, a source name, and a byte array providing the data. 
- `File` - A file or directory source. It has only the path to the file.

#### `name` -> `get_name(current_name, source)`

`name` plugins are chained one after the other. The first `name` plugin is provided an empty string for `current_name`.
Each subsequent `name` plugin is provided the output of the previous `name` plugin's `get_name` function. The `source`
parameter is the either `Raw` or `File` data source.

#### `upload` -> `upload(name, source)`

`upload` plugins are responsible for getting the source to the destination. 

#### `location` -> `get_location(name)`

The `get_location` function takes in the name of a source and returns a location that the source can now be accessed from
(e.g. a URL).

#### `feedback` -> `give_feedback(location)`

The `give_feedback` function takes output from `location` plugins and presents it to the user (e.g. printing to console,
desktop notification. etc...).