maxmustermann/termscp
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Updated contributing, issue templates and docs

Browse source
This commit is contained in:
veeso 2021-04-04 16:08:16 +02:00
parent 44ba1111af
commit 871a02c8b5
12 changed files with 384 additions and 224 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
.github/ISSUE_TEMPLATE/bug_report.md vendored
View file

@ -1,9 +1,9 @@
---
name: Bug report
about: Create a report to help me improving TermSCP
title: "[BUG]"
about: Create a report of the bug you've encountered
title: "[BUG] - ISSUE_TITLE"
labels: bug
assignees: ChristianVisintin
assignees: veeso
---
@ -24,7 +24,7 @@ A clear and concise description of what you expected to happen.
- OS: [e.g. GNU/Linux Debian 10]
- Architecture [Arm, x86_64, ...]
- Rust version
- TermSCP version
- termscp version
- Protocol used
- Remote server version and name

21
.github/ISSUE_TEMPLATE/feature_request.md vendored
View file

@ -1,12 +1,23 @@
---
name: Feature request
about: Suggest an idea for TermSCP
title: "[Feature Request]"
labels: enhancement
assignees: ChristianVisintin
about: Suggest an idea to improve termscp
title: "[Feature Request] - FEATURE_TITLE"
labels: "new feature"
assignees: veeso
---
## Description
Describe the feature you'd like to be added
Put here a brief introduction to your suggestion.
### Changes
The following changes to the application are expected
- ...
## Implementation
Provide any kind of suggestion you propose on how to implement the feature.
If you have none, delete this section.

8
.github/ISSUE_TEMPLATE/question.md vendored Normal file
View file

@ -0,0 +1,8 @@
---
name: Question
about: Ask what you want about the project
title: "[QUESTION] - TITLE"
labels: question
assignees: veeso
---

9
.github/PULL_REQUEST_TEMPLATE.md vendored
View file

@ -1,4 +1,4 @@
# Pull Request Title
# ISSUE _NUMBER_ - PULL_REQUEST_TITLE
Fixes # (issue)
@ -25,7 +25,10 @@ Please select relevant options.
- [ ] My code follows the contribution guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I formatted the code with `cargo fmt`
- [ ] I checked my code using `cargo clippy` and reports no warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] Any dependent changes have been merged and published in downstream modules
- [ ] I have introduced no new *C-bindings*
- [ ] The changes I've made are Windows, MacOS, UNIX, Linux compatible (or I've handled them using `cfg target_os`)
- [ ] I increased or maintained the code coverage for the project, compared to the previous commit

307
CONTRIBUTING.md
View file

@ -4,14 +4,90 @@ Before contributing to this repository, please first discuss the change you wish
Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
- [Contributing](#contributing)
- [Project mission](#project-mission)
- [Project goals](#project-goals)
- [Open an issue](#open-an-issue)
- [Questions](#questions)
- [Bug reports](#bug-reports)
- [Feature requests](#feature-requests)
- [Preferred contributions](#preferred-contributions)
- [Pull Request Process](#pull-request-process)
- [Software guidelines](#software-guidelines)
- [Developer contributions guide](#developer-contributions-guide)
- [How TermSCP works](#how-termscp-works)
- [Activities](#activities)
- [The Context](#the-context)
- [Tests fails due to receivers](#tests-fails-due-to-receivers)
- [Implementing File Transfers](#implementing-file-transfers)
---
## Project mission
TermSCP was born because, as a terminal lover and Linux user, I wanted something like WinSCP on Linux and on terminal. I my previous job I used SFTP/SCP pratically everyday and that made me to desire an application like termscp so much, that eventually I started to work on it in the spare time. I saw there was a very cool library to create terminal user interface (`tui-rs`), so I started to code it. I wrote termscp as an experiment, I designed kinda nothing at the time. I just said
> Ok, there must be a `FileTransfer` trait somehow, I'll have more views, so I'll use something like Android activities, and there must be a module to interact with the local host".
And so in december 2020 I had the first version of termscp running and it worked, but was very simple, raw and minimal.
A lot of things have changed since them, both the features the project provides and my personal view of this project.
Today I don't see TermSCP as a WinSCP clone anymore. I've also thought about changing the name as the time passed by, but I liked it and it would be hard to change the name on the registries, etc.
Right now I see TermSCP as a **rich-featured file transfer client for terminals**. All I want is to provide all the features users need to use it correctly, I want it to be **safe and reliable** and eventually I want people to consider termscp **the first choice as a file transfer client**.
### Project goals
- Have support for all the most used file transfer protocol
- Provide all the features a file explorer requires
- Have a well designed application
- Make a reliable, safe and fast application
---
## Open an issue
Open an issue when:
- You have questions or concerns regarding the project or the application itself.
- You have a bug to report.
- You have a feature or a suggestion to improve termscp to submit.
### Questions
If you have a question open an issue using the `Question` template.
By default your question should already be labeled with the `question` label, if you need help with your installation, please also add the `help wanted` label.
Check the issue is always assigned to `veeso`.
### Bug reports
If you want to report an issue or a bug you've encountered while using termscp, open an issue using the `Bug report` template.
The `Bug` label should already be set and the issue should already be assigned to `veeso`.
Don't set other labels to your issue, not even priority.
When you open a bug try to be the most precise as possible in describing your issue. I'm not saying you should always be that precise, since sometimes it's very easy for maintainers to understand what you're talking about. Just try to be reasonable to understand sometimes we might not know what you're talking about or we just don't have the technical knowledge you might think.
Please always provide the environment you're working on and consider that we don't provide any support for older version of termscp, at least for those not classified as LTS (if we'll ever have them).
Last but not least: the template I've written must be used. Full stop.
Maintainers will may add additional labels to your issue:
- **duplicate**: the issue is duplicated; the reference to the related issue will be added to your description. Your issue will be closed.
- **priority**: this must be fixed asap
- **sorcery**: it is not possible to find out what's causing your bug, nor is reproducible on our test environments.
- **wontfix**: your bug has a very high ratio between the probability to encounter it and the difficult to fix it, or it just isn't a bug, but a feature.
### Feature requests
Whenever you have a good idea which chould improve the project, it is a good idea to submit it to the project owner.
The first thing you should do though, is not starting to write the code, but is to become concern about how termscp works, what kind
of contribution I appreciate and what kind of contribution I won't consider.
Said so, follow these steps:
- Read the contributing guidelines, entirely
- Think on whether your idea would fit in the project mission and guidelines or not
- Think about the impact your idea would have on the project
- Open an issue using the `feature request` template describing with accuracy your suggestion
- Wait for the maintainer feedback on your idea
If you want to implement the feature by yourself and your suggestion gets approved, start writing the code. Remember that on [docs.rs](https://docs.rs/termscp) there is the documentation for the project. Open a PR related to your issue. See [Pull request process for more details](#pull-request-process)
It is very important to follow these steps, since it will prevent you from working on a feature that will be rejected and trust me, none of us wants to deal with this situation.
Always mind that your suggestion, may be rejected: I'll always provide a feedback on the reasons that brought me to reject your feature, just try not to get mad about that.
---
@ -23,217 +99,38 @@ At the moment, these kind of contributions are more appreciated and should be pr
- New file transfers: for further details see [Implementing File Transfer](#implementing-file-transfers)
- Code optimizations: any optimization to the code is welcome
- See also features described in [Upcoming features](./README.md##upcoming-features-). Open an issue first though.
- A **logo** for the project: I'd really love to have a logo for termscp 💛
For any other kind of contribution, especially for new features, please submit an issue first.
For any other kind of contribution, especially for new features, please submit a new issue first.
## Pull Request Process
Let's make it simple and clear:
1. Open a PR with an **appropriate label** (e.g. bug, enhancement, ...).
2. Write a **properly documentation** compliant with **rustdoc** standard.
2. Write a **properly documentation** for your software compliant with **rustdoc** standard.
3. Write tests for your code. This doesn't apply necessarily for implementation regarding the user-interface module (`ui/activities`) and (if a test server is not available) for file transfers.
4. Report changes to the PR you opened, writing a report of what you changed and what you have introduced.
5. Update the `CHANGELOG.md` file with details of changes to the application. In changelog report changes under a chapter called `PR{PULL_REQUEST_NUMBER}` (e.g. PR12).
6. Request maintainers to merge your changes.
4. Check your code with `cargo clippy`.
5. Check if the CI for your commits reports three-green.
6. Report changes to the PR you opened, writing a report of what you changed and what you have introduced.
7. Update the `CHANGELOG.md` file with details of changes to the application. In changelog report changes under a chapter called `PR{PULL_REQUEST_NUMBER}` (e.g. PR12).
8. Assign a maintainer to the reviewers.
9. Request maintainers to merge your changes.
### Software guidelines
In addition to the process described for the PRs, I've also decided to introduce a list of guidelines to follow when writing the code, that should be followed:
1. **Let's stop the NPM apocalypse**: personally I'm against the abuse of dependencies we make in software projects and I think that NodeJS has opened the way to this drama (and has already gone too far). Nowadays nobody cares about adding hundreds of dependencies to their projects. Don't misunderstand me: I think that package managers are cool, but I'm totally against the abuse we're making of them. I think when we work on a project, we should try to use the minor quantity of dependencies as possible, especially because it's not hard to see how many libraries are getting abandoned right now, causing compatibility issues after a while. So please, when working on termscp, try not to add useless dependencies.
2. **No C-bindings**: personally I think that Rust still relies too much on C. And that's bad, really bad. Many libraries in Rust are just wrappers to C libraries, which is a huge problem, especially considering this is a multiplatform project. Everytime you add a C-binding to your project, you're forcing your users to install additional libraries to their systems. Sometimes these libraries are already installed on their systems (as happens for libssh2 or openssl in this case), but sometimes not. So if you really have to add a dependency to this project, please AVOID completely adding C-bounded libraries.
3. **Test units matter**: Whenever you implement something new to this project, always implement test units which cover the most cases as possible.
4. **Comments are useful**: Many people say that the code should be that simple to talk by itself about what it does, and comments should then be useless. I personally don't agree. I'm not saying they're wrong, but I'm just saying that this approach has, in my personal opinion, many aspects which are underrated:
1. What's obvious for me, might not be for the others.
2. Our capacity to work on a code depends mostly on **time and experience**, not on complexity: I'm not denying complexity matter, but the most decisive factor when working on code is the experience we've acquired working on it and the time we've spent. As the author of the project, I know the project like the back of my hands, but if I didn't work on it for a year, then I would probably have some problems in working on it again as the same speed as before. And do you know what's really time-saving in these cases? Comments.
## Developer contributions guide
Welcome to the contributions guide for TermSCP. This chapter DOESN'T contain the documentation for TermSCP, which can instead be found on Rust Docs at <https://docs.rs/termscp>
This chapter describes how TermSCP works and the guide lines to implement stuff such as file transfers and add features to the user interface.
### How TermSCP works
TermSCP is basically made up of 4 components:
- the **filetransfer**: the filetransfer takes care of managing the remote file system; it provides function to establish a connection with the remote, operating on the remote server file system (e.g. remove files, make directories, rename files, ...), read files and write files. The FileTransfer, as we'll see later, is actually a trait, and for each protocol a FileTransfer must be implement the trait.
- the **host**: the host module provides functions to interact with the local host file system.
- the **ui**: this module contains the implementation of the user interface, as we'll see in the next chapter, this is achieved through **activities**.
- the **activity_manager**: the activity manager takes care of managing activities, basically it runs the activities of the user interface, and chooses, based on their state, when is the moment to terminate the current activity and which activity to run after the current one.
In addition to the 4 main components, other have been added through the time:
- **config**: this module provides the configuration schema and serialization methods for it.
- **fs**: this modules exposes the FsEntry entity and the explorers. The explorers are structs which hold the content of the current directory; they also they take of filtering files up to your preferences and format file entries based on your configuration.
- **system**: the system module provides a way to actually interact with the configuration, the ssh key storage and with the bookmarks.
- **utils**: contains the utilities used by pretty much all the project.
#### Activities
Just a little paragraph about activities. Really, read the code and the documentation to have a clear idea of how the ui works.
I think there are many ways to implement a user interface and I've worked with different languages and frameworks in my career, so for this project I've decided to get what I like the most from different frameworks to implement it.
My approach was this:
- **Activities on top**: each "page" is an Activity and an `Activity Manager` handles them. I got inspired by Android for this case. I think that's a good way to implement the ui in case like this, where you have different pages, each one with their view, their components and their logics. Activities work with the `Context`, which is a data holder for different data, which are shared and common between the activities.
- **Activities display Views**: Each activity can show different views. A view is basically a list of **components**, each one with its properties. The view is a facade to the components and also handles the focus, which is the current active component. You cannot have more than one component active, so you need to handle this; but at the same time you also have to give focus to the previously active component if the current one is destroyed. So basically view takes care of all this stuff.
- **Components**: I've decided to write around `tui` in order to re-use widgets. To do so I've implemented the `Component` trait. To implement traits I got inspired by [React](https://reactjs.org/). Each component has its *Properties* and can have its *States*. Then each component must be able to handle input events and to be updated with new properties. Last but not least, each component must provide a method to **render** itself.
- **Messages: an Elm based approach**: I was really satisfied with my implementation choices; the problem at this point was solving one of the biggest teardrops I've ever had with this project: **events**. Input events were really a pain to handle, since I had to handle states in the activity to handle which component was enabled etc. To solve this I got inspired by a wonderful language I had recently studied, which is [Elm](https://elm-lang.org/). Basically in Elm you implement your ui using three basic functions: **update**, **view** and **init**. View and init were pretty much already implemented here, but at this point I decided to implement also something like the **elm update function**. I came out with a huge match case to handle events inside a recursive function, which you can basically find in the `update.rs` file inside each activity. This match case handles a tuple, made out of the **component id** and the **input event** received from the view. It matches the two propeties against the input event we want to handle for each component *et voilà*.
I've implemented a Trait called `Activity`, which, is a very very reduced version of the Android activity of course.
This trait provides only 3 methods:
- `on_create`: this method must initialize the activity; the context is passed to the activity, which will be the only owner of the Context, until the activity terminates.
- `on_draw`: this method must be called each time you want to perform an update of the user interface. This is basically the run method of the activity. This method also cares about handling input events. The developer shouldn't draw the interface on each call of this method (consider that this method might be called hundreds of times per second), but only when actually something has changed (for example after an input event has been raised).
- `will_umount`: this method was added in 0.4.0 and returns whethere the activity should be destroyed. If so returns an ExitReason, which indicates why the activity should be terminated. Based on the reason, the activity manager chooses whether to stop the execution of termscp or to start a new activity and which one.
- `on_destroy`: this method finalizes the activity and drops it; this method returns the Context to the caller (the activity manager).
#### The Context
The context is a structure which holds data which must be shared between activities. Everytime an Activity starts, the Context is taken by the activity, until it is destroyed, where finally the context is returned to the activity manager.
The context basically holds the following data:
- The **Localhost**: the local host structure
- The **File Transfer Params**: the current parameters set to connect to the remote
- The **Config Client**: the configuration client is a structure which provides functions to access the user configuration
- The **Store**: the store is a key-value storage which can hold any kind of data. This can be used to store states to share between activities or to keep persistence for heavy/slow tasks (such as checking for updates).
- The **Input handler**: the input handler is used to read input events from the keyboard
- The **Terminal**: the terminal is used to view the tui on the terminal
---
### Tests fails due to receivers
Yes. This happens quite often and is related to the fact that I'm using public SSH/SFTP/FTP server to test file receivers and sometimes this server go down for even a day or more. If your tests don't pass due to this, don't worry, submit the pull request and I'll take care of testing them by myself.
---
### Implementing File Transfers
This chapter describes how to implement a file transfer in TermSCP. A file transfer is a module which implements the `FileTransfer` trait. The file transfer provides different modules to interact with a remote server, which in addition to the most obvious methods, used to download and upload files, provides also methods to list files, delete files, create directories etc.
In the following steps I will describe how to implement a new file transfer, in this case I will be implementing the SCP file transfer (which I'm actually implementing the moment I'm writing this lines).
1. Add the Scp protocol to the `FileTransferProtocol` enum.
Move to `src/filetransfer/mod.rs` and add `Scp` to the `FileTransferProtocol` enum
```rs
/// ## FileTransferProtocol
///
/// This enum defines the different transfer protocol available in TermSCP
#[derive(std::cmp::PartialEq, std::fmt::Debug, std::clone::Clone)]
pub enum FileTransferProtocol {
Sftp,
Ftp(bool), // Bool is for secure (true => ftps)
Scp, // <-- here
}
```
In this case Scp is a "plain" enum type. If you need particular options, follow the implementation of `Ftp` which uses a boolean flag for indicating if using FTPS or FTP.
2. Implement the FileTransfer struct
Create a file at `src/filetransfer/mytransfer.rs`
Declare your file transfer struct
```rs
/// ## ScpFileTransfer
///
/// SFTP file transfer structure
pub struct ScpFileTransfer {
session: Option<Session>,
sftp: Option<Sftp>,
wrkdir: PathBuf,
}
```
3. Implement the `FileTransfer` trait for it
You'll have to implement the following methods for your file transfer:
- connect: connect to remote server
- disconnect: disconnect from remote server
- is_connected: returns whether the file transfer is connected to remote
- pwd: get working directory
- change_dir: change working directory.
- list_dir: get files and directories at a certain path
- mkdir: make a new directory. Return an error in case the directory already exists
- remove: remove a file or a directory. In case the protocol doesn't support recursive removing of directories you MUST implement this through a recursive algorithm
- rename: rename a file or a directory
- stat: returns detail for a certain path
- send_file: opens a stream to a remote path for write purposes (write a remote file)
- recv_file: opens a stream to a remote path for read purposes (write a local file)
- on_sent: finalize a stream when writing a remote file. In case it's not necessary just return `Ok(())`
- on_recv: fianlize a stream when reading a remote file. In case it's not necessary just return `Ok(())`
In case the protocol you're working on doesn't support any of this features, just return `Err(FileTransferError::new(FileTransferErrorType::UnsupportedFeature))`
4. Add your transfer to filetransfers:
Move to `src/filetransfer/mod.rs` and declare your file transfer:
```rs
// Transfers
pub mod ftp_transfer;
pub mod scp_transfer; // <-- here
pub mod sftp_transfer;
```
5. Handle FileTransfer in `FileTransferActivity::new`
Move to `src/ui/activities/filetransfer_activity/mod.rs` and add the new protocol to the client match
```rs
client: match protocol {
FileTransferProtocol::Sftp => Box::new(SftpFileTransfer::new()),
FileTransferProtocol::Ftp(ftps) => Box::new(FtpFileTransfer::new(ftps)),
FileTransferProtocol::Scp => Box::new(ScpFileTransfer::new()), // <--- here
},
```
6. Handle right/left input events in `AuthActivity`:
Move to `src/ui/activities/auth_activity.rs` and handle the new protocol in `handle_input_event_mode_text` for `KeyCode::Left` and `KeyCode::Right`.
Consider that the order they "rotate" must match the way they will be drawned in the interface.
For newer protocols, please put them always at the end of the list. In this list I won't, because Scp is more important than Ftp imo.
```rs
KeyCode::Left => {
// If current field is Protocol handle event... (move element left)
if self.selected_field == InputField::Protocol {
self.protocol = match self.protocol {
FileTransferProtocol::Sftp => FileTransferProtocol::Ftp(true), // End of list (wrap)
FileTransferProtocol::Scp => FileTransferProtocol::Sftp,
FileTransferProtocol::Ftp(ftps) => match ftps {
false => FileTransferProtocol::Scp,
true => FileTransferProtocol::Ftp(false),
}
};
}
}
KeyCode::Right => {
// If current field is Protocol handle event... ( move element right )
if self.selected_field == InputField::Protocol {
self.protocol = match self.protocol {
FileTransferProtocol::Sftp => FileTransferProtocol::Scp,
FileTransferProtocol::Scp => FileTransferProtocol::Ftp(false),
FileTransferProtocol::Ftp(ftps) => match ftps {
false => FileTransferProtocol::Ftp(true),
true => FileTransferProtocol::Sftp, // End of list (wrap)
}
};
}
}
```
7. Add your new file transfer to the protocol input field
Move to `AuthActivity::draw_protocol_select` method.
Here add your new protocol to the `Spans` vector and to the match case, which chooses which element to highlight.
```rs
let protocols: Vec<Spans> = vec![Spans::from("SFTP"), Spans::from("SCP"), Spans::from("FTP"), Spans::from("FTPS")];
let index: usize = match self.protocol {
FileTransferProtocol::Sftp => 0,
FileTransferProtocol::Scp => 1,
FileTransferProtocol::Ftp(ftps) => match ftps {
false => 2,
true => 3,
}
};
```
You can view the developer guide [here](docs/developer.md).
---

11
README.md
View file

@ -35,7 +35,7 @@ Current version: 0.4.1 FIXME: (27/03/2021)
- [Documentation 📚](#documentation-)
- [Known issues 🧻](#known-issues-)
- [Upcoming Features 🧪](#upcoming-features-)
- [Contributions 🤝🏻](#contributions-)
- [Contributing and issues 🤝🏻](#contributing-and-issues-)
- [Changelog ⏳](#changelog-)
- [Powered by 🚀](#powered-by-)
- [Gallery 🎬](#gallery-)
@ -395,11 +395,14 @@ Anyway there are some ideas which I'd like to implement. If you want to start wo
---
## Contributions 🤝🏻
## Contributing and issues 🤝🏻
Contributions are welcome! 😉
Contributions, bug reports, new features and questions are welcome! 😉
If you have any question or concern, or you want to suggest a new feature, or you want just want to improve termscp, feel free to open an issue or a PR.
If you think you can contribute to TermSCP, please follow [TermSCP's contributions guide](CONTRIBUTING.md)
Please follow [our contributing guidelines](CONTRIBUTING.md)
---
## Changelog ⏳

BIN
docs/bl.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 271 KiB

35
docs/deploy.md Normal file
View file

@ -0,0 +1,35 @@
# Deploy checklist
Document audience: project maintainers
- [Deploy checklist](#deploy-checklist)
- [Description](#description)
- [Checklist](#checklist)
## Description
This document describes the checklist that must be fulfilled before releasing a new version of termscp.
## Checklist
- [ ] The latest build didn't report any error in the CI
- [ ] All commands when using SFTP work
- [ ] All commands when using SCP work
- [ ] All commands when using FTP work
- [ ] It is possible to load bookmarks
- [ ] Recent connections get saved
- [ ] Update versions and release date in readme, changelog and cargo.toml
- [ ] Build on MacOS
- [ ] Update sha256 and version on homebrew repository
- [ ] Build on Windows
- [ ] Update sha256 and version in chocolatey repository
- [ ] Create chocolatey package
- [ ] Build Linux version using docker from `dist/build/build.sh`
- [ ] Update sha256 and version in AUR files
- [ ] Create release and attach the following artifacts
- [ ] Deb package
- [ ] RPM package
- [ ] MacOs tar.gz
- [ ] Windows nupkg
- [ ] Windows zip
- [ ] AUR tar.gz

206
docs/developer.md Normal file
View file

@ -0,0 +1,206 @@
# Developer Manual
Document audience: developers
- [Developer Manual](#developer-manual)
- [How TermSCP works](#how-termscp-works)
- [Activities](#activities)
- [The Context](#the-context)
- [Tests fails due to receivers](#tests-fails-due-to-receivers)
- [Implementing File Transfers](#implementing-file-transfers)
Welcome to the developer manual for TermSCP. This chapter DOESN'T contain the documentation for TermSCP modules, which can instead be found on Rust Docs at <https://docs.rs/termscp>
This chapter describes how TermSCP works and the guide lines to implement stuff such as file transfers and add features to the user interface.
## How TermSCP works
TermSCP is basically made up of 4 components:
- the **filetransfer**: the filetransfer takes care of managing the remote file system; it provides function to establish a connection with the remote, operating on the remote server file system (e.g. remove files, make directories, rename files, ...), read files and write files. The FileTransfer, as we'll see later, is actually a trait, and for each protocol a FileTransfer must be implement the trait.
- the **host**: the host module provides functions to interact with the local host file system.
- the **ui**: this module contains the implementation of the user interface, as we'll see in the next chapter, this is achieved through **activities**.
- the **activity_manager**: the activity manager takes care of managing activities, basically it runs the activities of the user interface, and chooses, based on their state, when is the moment to terminate the current activity and which activity to run after the current one.
In addition to the 4 main components, other have been added through the time:
- **config**: this module provides the configuration schema and serialization methods for it.
- **fs**: this modules exposes the FsEntry entity and the explorers. The explorers are structs which hold the content of the current directory; they also they take of filtering files up to your preferences and format file entries based on your configuration.
- **system**: the system module provides a way to actually interact with the configuration, the ssh key storage and with the bookmarks.
- **utils**: contains the utilities used by pretty much all the project.
## Activities
Just a little paragraph about activities. Really, read the code and the documentation to have a clear idea of how the ui works.
I think there are many ways to implement a user interface and I've worked with different languages and frameworks in my career, so for this project I've decided to get what I like the most from different frameworks to implement it.
My approach was this:
- **Activities on top**: each "page" is an Activity and an `Activity Manager` handles them. I got inspired by Android for this case. I think that's a good way to implement the ui in case like this, where you have different pages, each one with their view, their components and their logics. Activities work with the `Context`, which is a data holder for different data, which are shared and common between the activities.
- **Activities display Views**: Each activity can show different views. A view is basically a list of **components**, each one with its properties. The view is a facade to the components and also handles the focus, which is the current active component. You cannot have more than one component active, so you need to handle this; but at the same time you also have to give focus to the previously active component if the current one is destroyed. So basically view takes care of all this stuff.
- **Components**: I've decided to write around `tui` in order to re-use widgets. To do so I've implemented the `Component` trait. To implement traits I got inspired by [React](https://reactjs.org/). Each component has its *Properties* and can have its *States*. Then each component must be able to handle input events and to be updated with new properties. Last but not least, each component must provide a method to **render** itself.
- **Messages: an Elm based approach**: I was really satisfied with my implementation choices; the problem at this point was solving one of the biggest teardrops I've ever had with this project: **events**. Input events were really a pain to handle, since I had to handle states in the activity to handle which component was enabled etc. To solve this I got inspired by a wonderful language I had recently studied, which is [Elm](https://elm-lang.org/). Basically in Elm you implement your ui using three basic functions: **update**, **view** and **init**. View and init were pretty much already implemented here, but at this point I decided to implement also something like the **elm update function**. I came out with a huge match case to handle events inside a recursive function, which you can basically find in the `update.rs` file inside each activity. This match case handles a tuple, made out of the **component id** and the **input event** received from the view. It matches the two propeties against the input event we want to handle for each component *et voilà*.
I've implemented a Trait called `Activity`, which, is a very very reduced version of the Android activity of course.
This trait provides only 3 methods:
- `on_create`: this method must initialize the activity; the context is passed to the activity, which will be the only owner of the Context, until the activity terminates.
- `on_draw`: this method must be called each time you want to perform an update of the user interface. This is basically the run method of the activity. This method also cares about handling input events. The developer shouldn't draw the interface on each call of this method (consider that this method might be called hundreds of times per second), but only when actually something has changed (for example after an input event has been raised).
- `will_umount`: this method was added in 0.4.0 and returns whethere the activity should be destroyed. If so returns an ExitReason, which indicates why the activity should be terminated. Based on the reason, the activity manager chooses whether to stop the execution of termscp or to start a new activity and which one.
- `on_destroy`: this method finalizes the activity and drops it; this method returns the Context to the caller (the activity manager).
### The Context
The context is a structure which holds data which must be shared between activities. Everytime an Activity starts, the Context is taken by the activity, until it is destroyed, where finally the context is returned to the activity manager.
The context basically holds the following data:
- The **Localhost**: the local host structure
- The **File Transfer Params**: the current parameters set to connect to the remote
- The **Config Client**: the configuration client is a structure which provides functions to access the user configuration
- The **Store**: the store is a key-value storage which can hold any kind of data. This can be used to store states to share between activities or to keep persistence for heavy/slow tasks (such as checking for updates).
- The **Input handler**: the input handler is used to read input events from the keyboard
- The **Terminal**: the terminal is used to view the tui on the terminal
---
## Tests fails due to receivers
Yes. This happens quite often and is related to the fact that I'm using public SSH/SFTP/FTP server to test file receivers and sometimes this server go down for even a day or more. If your tests don't pass due to this, don't worry, submit the pull request and I'll take care of testing them by myself.
---
## Implementing File Transfers
This chapter describes how to implement a file transfer in TermSCP. A file transfer is a module which implements the `FileTransfer` trait. The file transfer provides different modules to interact with a remote server, which in addition to the most obvious methods, used to download and upload files, provides also methods to list files, delete files, create directories etc.
In the following steps I will describe how to implement a new file transfer, in this case I will be implementing the SCP file transfer (which I'm actually implementing the moment I'm writing this lines).
1. Add the Scp protocol to the `FileTransferProtocol` enum.
Move to `src/filetransfer/mod.rs` and add `Scp` to the `FileTransferProtocol` enum
```rs
/// ## FileTransferProtocol
///
/// This enum defines the different transfer protocol available in TermSCP
#[derive(std::cmp::PartialEq, std::fmt::Debug, std::clone::Clone)]
pub enum FileTransferProtocol {
Sftp,
Ftp(bool), // Bool is for secure (true => ftps)
Scp, // <-- here
}
```
In this case Scp is a "plain" enum type. If you need particular options, follow the implementation of `Ftp` which uses a boolean flag for indicating if using FTPS or FTP.
2. Implement the FileTransfer struct
Create a file at `src/filetransfer/mytransfer.rs`
Declare your file transfer struct
```rs
/// ## ScpFileTransfer
///
/// SFTP file transfer structure
pub struct ScpFileTransfer {
session: Option<Session>,
sftp: Option<Sftp>,
wrkdir: PathBuf,
}
```
3. Implement the `FileTransfer` trait for it
You'll have to implement the following methods for your file transfer:
- connect: connect to remote server
- disconnect: disconnect from remote server
- is_connected: returns whether the file transfer is connected to remote
- pwd: get working directory
- change_dir: change working directory.
- list_dir: get files and directories at a certain path
- mkdir: make a new directory. Return an error in case the directory already exists
- remove: remove a file or a directory. In case the protocol doesn't support recursive removing of directories you MUST implement this through a recursive algorithm
- rename: rename a file or a directory
- stat: returns detail for a certain path
- send_file: opens a stream to a remote path for write purposes (write a remote file)
- recv_file: opens a stream to a remote path for read purposes (write a local file)
- on_sent: finalize a stream when writing a remote file. In case it's not necessary just return `Ok(())`
- on_recv: fianlize a stream when reading a remote file. In case it's not necessary just return `Ok(())`
In case the protocol you're working on doesn't support any of this features, just return `Err(FileTransferError::new(FileTransferErrorType::UnsupportedFeature))`
4. Add your transfer to filetransfers:
Move to `src/filetransfer/mod.rs` and declare your file transfer:
```rs
// Transfers
pub mod ftp_transfer;
pub mod scp_transfer; // <-- here
pub mod sftp_transfer;
```
5. Handle FileTransfer in `FileTransferActivity::new`
Move to `src/ui/activities/filetransfer_activity/mod.rs` and add the new protocol to the client match
```rs
client: match protocol {
FileTransferProtocol::Sftp => Box::new(SftpFileTransfer::new()),
FileTransferProtocol::Ftp(ftps) => Box::new(FtpFileTransfer::new(ftps)),
FileTransferProtocol::Scp => Box::new(ScpFileTransfer::new()), // <--- here
},
```
6. Handle right/left input events in `AuthActivity`:
Move to `src/ui/activities/auth_activity.rs` and handle the new protocol in `handle_input_event_mode_text` for `KeyCode::Left` and `KeyCode::Right`.
Consider that the order they "rotate" must match the way they will be drawned in the interface.
For newer protocols, please put them always at the end of the list. In this list I won't, because Scp is more important than Ftp imo.
```rs
KeyCode::Left => {
// If current field is Protocol handle event... (move element left)
if self.selected_field == InputField::Protocol {
self.protocol = match self.protocol {
FileTransferProtocol::Sftp => FileTransferProtocol::Ftp(true), // End of list (wrap)
FileTransferProtocol::Scp => FileTransferProtocol::Sftp,
FileTransferProtocol::Ftp(ftps) => match ftps {
false => FileTransferProtocol::Scp,
true => FileTransferProtocol::Ftp(false),
}
};
}
}
KeyCode::Right => {
// If current field is Protocol handle event... ( move element right )
if self.selected_field == InputField::Protocol {
self.protocol = match self.protocol {
FileTransferProtocol::Sftp => FileTransferProtocol::Scp,
FileTransferProtocol::Scp => FileTransferProtocol::Ftp(false),
FileTransferProtocol::Ftp(ftps) => match ftps {
false => FileTransferProtocol::Ftp(true),
true => FileTransferProtocol::Sftp, // End of list (wrap)
}
};
}
}
```
7. Add your new file transfer to the protocol input field
Move to `AuthActivity::draw_protocol_select` method.
Here add your new protocol to the `Spans` vector and to the match case, which chooses which element to highlight.
```rs
let protocols: Vec<Spans> = vec![Spans::from("SFTP"), Spans::from("SCP"), Spans::from("FTP"), Spans::from("FTPS")];
let index: usize = match self.protocol {
FileTransferProtocol::Sftp => 0,
FileTransferProtocol::Scp => 1,
FileTransferProtocol::Ftp(ftps) => match ftps {
false => 2,
true => 3,
}
};
```

1
docs/drawio/UI.drawio
View file

@ -1 +0,0 @@
<mxfile host="Electron" modified="2020-11-21T19:08:13.709Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.3.1 Chrome/83.0.4103.119 Electron/9.0.5 Safari/537.36" etag="CH09h_mpCNwCuwQp3CzT" version="13.3.1" type="device" pages="2"><diagram id="SlpWaeKyUTlHltKKkHdB" name="ScpActivity">7ZlRk5owEMc/DY/HABGEx2rv2pnWmXaczj3nJEKmgdAQD+yn7wJBoOhUrbbcTHwx2SSb5L+/4EoMtEzKDwJn8YqHhBmOFZYGem84ju26FnxVln1j8QO3MUSChqpTZ1jTn0QZ1bhoR0OSDzpKzpmk2dC44WlKNnJgw0LwYthty9lw1gxHZGRYbzAbW59pKGO1C2fe2T8SGsXtzLYXNC0JbjurneQxDnnRM6FHAy0F57IpJeWSsEq8Vpdm3NOJ1sPCBEnlOQOyRbEsv31ixSv+vi6c588r9vXBaby8YrZTG1aLlftWAcF3aUgqJ5aBFkVMJVlneFO1FhBzsMUyYVCzobiljC054wLqKU+h00LNQIQk5cml2wdBgCTCEyLFHrqoAchEqBmzH9JRdCFBgWd6KipxLyJopvpiRUJ0cN+JBQWl1wXaoTeh3azl77R0M8s6pptj+t6dpJsdkc5jMPPiBQqRrLfeGLYc9tkX1fux423DQ14/MN5BB9Ck7BpbL1+qU6g8wUobZ8MJwNyb9MYBxIxGKVQZ2crbxBMo9/58Fo4E1L3XOXB1MK8/nO60YumNYvlEGUlxQkBVnFQapS95Vu/e+semGo8b+seS3nZbGREJzXPK0/w6H7xIiahTIb7L3gC+o2fR/Bi/8Os9GyPs3QvhuUZYI3x1ejQFgn1NsCb4fILNwA96H3+YUaAJAB1ooDXQl2QVbh/o+RDoYAJAt3m6JloT/ddEH/7N/VeibU20JvqStNm0+p/f3klNIeuwxy+3NdIa6bNflE8i0RhfMmiGNcOnGbaHqcYUM43x5c+K5Hl1D+tYL7y8m8wbEBGi2Vw2rJV/u603N8+Oe6NAmEEwkB55Y+l92zUteyz94clzgfZQ7a6S67behTx6/AU=</diagram><diagram id="SK1VvSCf6-f5suE94Ksw" name="AuthActivity">5ZfRbpswFIafhstIAQNtL1OarlI1qUq6RdrNZLADnowPs00ge/qZYCA0ldZOSiqVK+z/2Mec/zuWwEFRXn+RuMi+AqHc8eakdtCd43luEMzNo1H2rXJ9E7RCKhmxiwZhzf5QK9p9ackIVaOFGoBrVozFBISgiR5pWEqoxsu2wMenFjilJ8I6wfxU3TCiM1uFdzXoD5SlWXeyG960kRx3i20lKsMEqiMJLR0USQDdjvI6orwxr/Pl8ennZvUQzVZ3uwXDz8pfPaNZm+z+PVv6EiQV+r9Tb/ax+q59lCz5D/5rN4sf0z71DvPS+mVr1fvOQAmlILRJMnfQbZUxTdcFTppoZVrGaJnOuZm5ZrhlnEfAQZq5AEEbCYS2beEFZo45S4WZcLo1xdzaF6BS0/oFsX+U6/YMTPNSyKmWe7PP9qlvqVXH0K2WHQFHXaNi22hpn2ow0wysn+/w1jvxdlHqzNTEEqwZiKk5HZ7LaPRKE4dcW0dGHoe/S+gCM3XwamEWuH5RD0EzSu3zkCXuhAUhkip12NOGzPvGL5cbrT23kz8HZnf+Rs7+uTj7l+L8BFJPFPJbL/PZIAcXgyxBQwK83aQob74+Jkj8+qOJh5ci/k1RKXBOp3m1++/YDwN9dbGrjZWqQJIWNM4bJiJWxRjyZMCH5wNvpsMP0CF29BuJln8B</diagram></mxfile>

1
docs/drawio/bl.drawio
View file

@ -1 +0,0 @@
<mxfile host="Electron" modified="2021-03-02T08:14:29.978Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.6.2 Chrome/83.0.4103.122 Electron/9.2.0 Safari/537.36" etag="1sEcOODuVA3fk4xHo3nz" version="13.6.2" type="device"><diagram id="38W8qqbr2ERVeYZfRmVD" name="Page-1">7Vxbc5s4FP41ftyOQVwfEztpdnbTdCad7fZpRwHZqAHECPnWX7/CCHMRiXESLEKTyQM6SEJ83zk6F5RMwCzafqYwCW6Jj8KJPvW3EzCf6Lpm6Pok+536u1ziaFouWFLsi06l4B7/QkI4FdIV9lFa68gICRlO6kKPxDHyWE0GKSWbercFCetPTeASSYJ7D4ay9Dv2WSDeQrdL+Q3Cy6B4sma5+Z0IFp3Fm6QB9MmmIgJXEzCjhLD8KtrOUJiBV+CSj7t+4u5hYRTFrMsAJw1dfLf6Mv/vzvxye3fz7Xty/Ycp1sZ2xQsjn7+/aBLKArIkMQyvSuklJavYR9msU94q+/xNSMKFGhf+RIztBJlwxQgXBSwKxV20xezfbPgnU7R+VO7Mt2LmfWMnGgsSMzGhZvF2vu5ssU/CIUQpWVEPPYNBoVaQLhF7pp9+II1rOyIRYnTHx1EUQobX9XVAoXbLQ7+SGX4hyDmBKOuDqM5EAZVE2R9EdSbKUEmUmHcNw5V40v0uZSiS+KuzswkwQ/cJ3AOw4U6vzkT6iJgXiMYCh+GMhITuJwKeh8zFIuvEKHlElTvAAi7wnyRljShD2+dpkWEsBljCAQkPDKaivSn9mVY4qaDiy4pxb468LiH/F9rdM0IzX9wb+ouFx3/Ojn4dfMNWDT6QwL8k5DGC9DEdHfbW0MA3JPBnJF7g5diQB4NTe01X6pcrXrn00Wf3y05Hv6w9we55HLPuqA2h7O4xFGeA7qqjsvaP6s1y3L41IJIrSagCksFULcn6i0jWP0g+hWRHcncXHn8qZnxqK+Trvnyg/GqZXd3CmId/tMfo20cPzsO5PaFp1j2ho9wRqk1QT3CEB7vTakb3yVRndlrXzFYzVdqdptaD/i4cW6/keD/0glK4q3RICI5ZWpn5ayYoN5RDPVlsKJrWKPse6+9OG/qVr6DUtsOrvEIB3XengBWdU+zbuyvgAPWvH30CmlJ9OqGqOsRgsbNCqY0Wi2XWqyM89GIy+WGIkxQdDwhhmuRfBRd4m6lCI0JsYN5SO3HdZyPGN4gQgVs3qJZSidMSIDq9BYhyhTDgD9Gnsg3uuanjHeJlzK89/vI8mAeXGTTYg+GFuBFh38+tE6X4F3zYT5Xpv9h3+Lzm5cScZ3Nxg0wFO/0E54Z7NDg3W6DXe4Nerg9e4xB9ozBOF73mRkq+TJgNV2JYypMjU96CYLyGPZbG1UBvNJBXDrwlAf9nnKyYXCe4gTHfQEZnCw1CNOWmoBsqQ67i+jUh/CGlPH/EVTB1POJSelYBqP0ockoRdghkaUrPKwDFZ7Ve9llkKDlQZ5KBUpKLZbaWzMddGVcfhOgDOg057WZgwymb6qCjgTlK7UtObn+HGoPdDC+B4iKDLsf7JJ6jDAR5o3vvZQbLPb7TueesMxSn1yvo38UziiCTz9+9d/AN26yrfktm1ab6/YHvtqk+hZvRQW81d52W+pp9TuiBvPtH+48fAVyPT/PNaR1+oFrzgeKDXYPINoHRMU4CtspACcil6H8wkveod56E2HbDRpQfVAVyZHQz0s8vdnOD0mTwrXNuUIbSetgpNc8+Nyi74wZlKD0lbCitT7/wSMBQqmHdOVZbn5bzlBmJEhJnLzxyT2Qq/zMtICcq+UGACMbjS9LtRpLe9jH6rNGy0fIHiqwtQx9Tocp1Giy43VjorVBlyCnjV0oS+UDAmFho2oLVEpi9EQu8Wf4LhPy4YPmPJMDV/w==</diagram></mxfile>

1
docs/drawio/component_lifecycle.drawio
View file

@ -1 +0,0 @@
<mxfile host="Electron" modified="2021-03-04T08:07:06.708Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.3.1 Chrome/83.0.4103.119 Electron/9.0.5 Safari/537.36" etag="hf5xr88nEHbSVkpX1Y-k" version="13.3.1" type="device"><diagram id="tfe7Y5e8DOWIlyiIXn_Y" name="Page-1">7Vxbc6M2FP41nmkf2gGEMDwmTtLOdNN2Jp1205cMBhmrwYgKsbb3168wwlxEbOIEZOLNS5CQZOkcfd+5SPYEzFabX6gbL++Jj8KJofmbCbiZGIYOocb/ZTXbvMZ2YF4RUOyLRmXFA/6KRKXoF6TYR0mtISMkZDiuV3okipDHanUupWRdb7YgYf1TYzdAUsWD54Zy7T/YZ0uxCmNa1v+KcLAsPlm3nPzNyi0ai5UkS9cn60oVuJ2AGSWE5U+rzQyFmfAKueT97l54u58YRRHr0iFBd49//Wv8hmafV08PC+p8ur/5CeSjfHHDVCz4ymP4C2ZbMWm2LSTBR+NC54Xr9RIz9BC7XvZmzfXO65ZsFfKSzh89ssKeeF7gMJyRkNDdGMDz0dye8/qEUfKMKm+ABRzgZz1IxMQ20C1eFhNElKHNiyvX9/LkGxGRFWKUL0ATHQoNiC1oiuK61KdeNFlWdGmLOldsoWA/cCll/iAE/QqhF3u7Klyf7zpRJJQtSUAiN7wta68pSSMfZcNqvFS2+URILIT9H2JsK2TnpozU1YI2mH3Ouv8MRemx8uZmI0beFbZFIeLrrXTKio/Vd2W3Xano167EbJGHVchlQlLqoQPCE8BjLg0QO9DObt8SFIUu3+D1eby7hqcSrB74hNnpmHKTOGe3Bd5km6AOsoa0G6BDu7+DoHsHkIGpeQxl9qAgA0pBVoFYCbjRgMzuCDLdUIkyW0JZwI0p7xTFKf9vhXzq13PKn4LsCX3ZyeFO2hd0SVbzNHmlZTsMug6W7j1AZ1o10OnTFtsGLBl2utYb7qyxGLce8ZPjoguAoEoAFdOsIIhEP/woKZC7rnH2GFPioaQDUOau9xzslPpHykIcoRMA5CG4WPQNIN2u+4Z7e3TMObR6w48p6eSRB0BNlfAls4aLEOIg4s8eXzriorrOBIN5JHMlXqyw7+doQwn+6s53Q2VAiAmO2G4d8HoCb7KxOMASoZuefHJLrzOXY0qCN1vkbvQld2M0vHWG/oIOO/KdodRhKKbZGu423YWC7HgonwTnQYmD+BRNSjQ15ZQoh1P3LSp5mRJDtGBnT4iwLnZgyWKHgxIiVEqIJwVQNTos2VEBIXaOoN7qAO66XlHqbisNxAYuR/4zq6hgvJESc5q5wyPtTaA19lc+g3K37ZfyBtjL8V0a+y5DF+2h2o5qOi4+rNWKapxfw9e4q6Pg5kaYvSfiqg60QclZv3QdWIZyHThKDeS4Iwaja4bEUJrIB1OVOtYnpzhB49NxnqFUpeNimhUu5V5ATKJswVJYSNH/KaZZRqb5JndOPlaCWZ8aNdaFuvIEs3EZCbKm39dm7wZNkAG1B2ojN3dd40GgNEFmtBypIfbEo6o4ueioy2rJxgwbdYHL8/gbGTFbedQFzO8UeDIFgq7eoK7W45e9wXv3GfGaCK2zpWdceB5MqOQ4YNp2xWBQJjSVOiIjj8kKX/0oCk2ljoipNrdyKTpWy7SWxLTJkqSh/5SuuCbl25K9hNGDuJMQNA732q6ZDBtGA9nV/528woMcRxQNGoKHxTUPZVG0I4n9Dkc4Wcp893HuBkNo17Sga0De/4PeDjblaOojJpEsu37LytR0tdvfVJpPH3kEZXbOpztvtOsnXSqYWnWu5bbr8K0C6DRpod6hn2sFhRSr1wp2/saZJLgWC89znL4peao1ElzKL76acl5/Vh7DnGocD30Z7bjrN0BeX/m30Uz5UuTfOEt19CDyDnu7B5E3vW/lIofGdyt4uhXsepQCX9gVA2Uw5PiKr9VH9EzMzDCBrwnqJh4qNzPFIcLHjntNp0l5ih1/OJrT4x6pCxa/YHCeDrx5xB8/EwceyrF7zqzylRw3G+0cyHaQo5om2U6VH1pD2ad/3Tc3xsG2jcDXafnGzDt9dYMXy18MyQFV/u4KuP0G</diagram></mxfile>