Merge pull request #4 from manforowicz/example-pr

Improved cargo toml descriptions

.github/workflows/test.yml

@@ -1,10 +1,15 @@
+# GitHub workflow for automatically
+# testing code on push to main
+# and pull requests.
+
 name: Cargo Build & Test
 
 on:
   push:
     branches:
       - main
   pull_request:
+    types: [synchronize]
 
 env: 
   CARGO_TERM_COLOR: always

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+## Feature requests and bug reports
+
+To request features or report bugs, submit an
+[issue](https://github.com/manforowicz/gday/issues)
+on this GitHub repository.
+Please try to add as much details as you can.
+
+Feel free to share your experiences using gday, by submitting issues.
+
+## Contributing code
+
+Learn how to contribute by following GitHub's
+[Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)
+guide.
+
+Verify your code passes tests by running the cargo commands listed
+in the `pre-push` file.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marcin Anforowicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,48 +1,61 @@
-# Gday Project
+# gday
 
-**WORK IN PROGRESS - THIS PROJECT IS NOT READY YET**
+**Note: this project is still in early-development, so expect breaking changes.**
 
-Send files directly to anyone.
-
-## Example
+A command line tool for sending files.
 
 <pre>
 <b style="color:lime;">peer_1:</b> gday send msg.txt image.jpg
-<i>*Asks for confirmation*</i>
+<i>&lt;Asks for confirmation&gt;</i>
 Tell your mate to run "gday receive <b>1.188T.W3H.E</b>".
 <b>Transfer complete.</b>
 </pre>
 
 <pre>
 <b style="color:lime;">peer_2:</b> gday receive <b>1.188T.W3H.E</b>
-<i>*Asks for confirmation*</i>
+<i>&lt;Asks for confirmation&gt;</i>
 <b>Transfer complete.</b>
 </pre>
 
 [![asciicast](https://asciinema.org/a/662397.svg)](https://asciinema.org/a/662397)
 
-## Features
+## Installation
 
-- Uses [TCP Hole Punching](https://bford.info/pub/net/p2pnat/)
-with the help of a [gday_contact_exchange_server](/gday_contact_exchange_server/)
-to establish a direct peer-to-peer connection,
-even between different private networks.
-Note: This may not work on networks with very restrictive [NATs](https://en.wikipedia.org/wiki/Network_address_translation).
+### Executable
 
-- Since the transfer is always direct,
-  you can send huge amounts of data without affecting any relay servers.
+1. Go to [releases](https://github.com/manforowicz/gday/releases)
+and download the correct file for your platform.
+2. Extract the executable 
+(on Linux, try: `tar xf <file>`).
+3. Run the executable: `./<path to executable>/gday`
 
-- Doesn't require port forwarding.
+### Cargo
 
-- Automatically tries both IPv4 and IPv6.
+If you have `cargo`, run `cargo install gday`.
 
-- Uses password authenticated key exchange ([SPAKE2](https://datatracker.ietf.org/doc/rfc9382/))
-to derive a strong encryption key from a weak shared password.
+### Brew
+
+If you have `brew`, run `brew install manforowicz/tap/gday`.
 
-- Authenticated encryption using [ChaCha20Poly1305](https://en.wikipedia.org/wiki/ChaCha20-Poly1305).
+## Features
+- File transfer is always direct, without relays.
+A server is only used to help the devices find each other.
+- Doesn't require port forwarding.
+- Files encrypted with streaming
+[ChaCha20Poly1305](https://en.wikipedia.org/wiki/ChaCha20-Poly1305).
+- Automatically tries both IPv4 and IPv6.
+- Immune to malicious servers trying to impersonate your peer.
+Uses password authenticated key exchange
+([SPAKE2](https://datatracker.ietf.org/doc/rfc9382/))
+to derive a strong encryption key from a weak shared password.
 
-Want to send files easily, securely, and directly, without a relay or port forwarding?
-Then go to the [gday page](gday/README.md).
+## How it works
+Uses [TCP Hole Punching](https://bford.info/pub/net/p2pnat/)
+with the help of a server
+to establish a direct peer-to-peer connection,
+even between different private networks.
+Note: This may not work on networks with very restrictive
+[NATs](https://en.wikipedia.org/wiki/Network_address_translation).
 
 ## Usage
 ```
@@ -70,13 +83,12 @@ I'm very grateful to their creators and contributors.
 <table>
     <tr>
         <th></th>
-        <th>Always direct (no relays)</th>
+        <th>Always direct (no relay)</th>
         <th>Can work beyond LAN, through most <a href="https://en.wikipedia.org/wiki/Network_address_translation">NATs</a></th>
-        <th>Works through restrictive <a href="https://en.wikipedia.org/wiki/Network_address_translation">NATs</a></th>
-        <th>Works without port forwarding or opening</th>
+        <th>Works through very strict <a href="https://en.wikipedia.org/wiki/Network_address_translation">NATs</a></th>
+        <th>No port forwarding</th>
         <th>Encrypted</th>
         <th>Can resume interrupted transfers</th>
-        <th>Free & open source</th>
     </tr>
     <tr>
         <td><strong><a href="https://github.com/manforowicz/gday">gday</a></strong></td>
@@ -86,7 +98,6 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>✅</td>
         <td>✅</td>
-        <td>✅</td>
     </tr>
     <tr>
         <td><a href="https://github.com/magic-wormhole/magic-wormhole">magic-wormhole</a></td>
@@ -96,7 +107,6 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>✅</td>
         <td>✅</td>
-        <td>✅</td>
     </tr>
     <tr>
         <td><a href="https://github.com/schollz/croc">croc</a></td>
@@ -106,27 +116,24 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>✅</td>
         <td>✅</td>
-        <td>✅</td>
     </tr>
-    <tr>
-        <td><a href="https://github.com/nirvik/iWant">iwant</a></td>
+        <tr>
+        <td><a href="https://github.com/psantosl/p2pcopy">p2pcopy</a></td>
+        <td>✅</td>
         <td>✅</td>
-        <td>❌</td>
         <td>❌</td>
         <td>✅</td>
         <td>❌</td>
         <td>❌</td>
-        <td>✅</td>
     </tr>
     <tr>
-        <td><a href="https://github.com/psantosl/p2pcopy">p2pcopy</a></td>
-        <td>✅</td>
+        <td><a href="https://github.com/nirvik/iWant">iwant</a></td>
         <td>✅</td>
         <td>❌</td>
+        <td>❌</td>
         <td>✅</td>
         <td>❌</td>
         <td>❌</td>
-        <td>✅</td>
     </tr>
     <tr>
         <td><a href="https://github.com/nils-werner/zget">zget</a></td>
@@ -136,7 +143,6 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>❌</td>
         <td>❌</td>
-        <td>✅</td>
     </tr>
     <tr>
         <td><a href="https://github.com/cowbell/sharedrop">sharedrop</a></td>
@@ -146,7 +152,6 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>✅</td>
         <td>❌</td>
-        <td>✅</td>
     </tr>
     <tr>
         <td><a href="https://github.com/kern/filepizza">filepizza</a></td>
@@ -156,37 +161,24 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>✅</td>
         <td>❌</td>
-        <td>✅</td>
-    </tr>
-    <tr>
-        <td><a href="https://github.com/zerotier/toss">toss</a></td>
-        <td>✅</td>
-        <td>❌</td>
-        <td>❌</td>
-        <td>✅</td>
-        <td>❌</td>
-        <td>❌</td>
-        <td>✅</td>
     </tr>
     <tr>
-        <td>Personal <a href="https://en.wikipedia.org/wiki/Secure_Shell">SSH</a> or <a href="https://en.wikipedia.org/wiki/HTTPS">HTTPS</a> server</td>
+        <td>Personal <a href="https://en.wikipedia.org/wiki/Secure_Shell">SSH</a> or <a href="https://en.wikipedia.org/wiki/HTTPS">HTTPS</a></td>
         <td>✅</td>
         <td>✅</td>
         <td>✅</td>
         <td>❌</td>
         <td>✅</td>
         <td>❌</td>
-        <td>✅</td>
     </tr>
     <tr>
-        <td>Personal <a href="https://en.wikipedia.org/wiki/File_Transfer_Protocol">FTP</a> server</td>
+        <td>Personal <a href="https://en.wikipedia.org/wiki/File_Transfer_Protocol">FTP</a></td>
         <td>✅</td>
         <td>✅</td>
         <td>✅</td>
         <td>❌</td>
         <td>❌</td>
         <td>❌</td>
-        <td>✅</td>
     </tr>
     <tr>
         <td>Dropbox, Google Drive, etc.</td>
@@ -196,7 +188,6 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>✅</td>
         <td>❌</td>
-        <td>❌</td>
     </tr>
     <tr>
         <td>Delivering a USB drive</td>
@@ -206,11 +197,10 @@ I'm very grateful to their creators and contributors.
         <td>✅</td>
         <td>✅</td>
         <td>❌</td>
-        <td>❓</td>
     </tr>
 </table>
 
-Open an issue on GitHub to add more projects.
+Open an [issue](https://github.com/manforowicz/gday/issues) on GitHub to add more projects.
 
 ## In this repository
 
@@ -220,9 +210,6 @@ Open an issue on GitHub to add more projects.
 - [gday_encryption](/gday_encryption/) - Encrypts an IO stream.
 - [gday_contact_exchange_protocol](/gday_contact_exchange_protocol/) - Protocol for two peers to share their socket
 addresses via a server.
-- [gday_file_offer_protocol](/gday_file_offer_protocol/) - Protocol for peers to offer to send each other files.
-
-![gday crate dependency graph](/images/dependency_graph.svg)
+- [gday_file_transfer](/gday_file_offer_protocol/) - Protocol for transferring files over a direct connection.s
 
-## Motivation
-![xkcd about sending files](/images/file_transfer.png)
+![gday crate dependency graph](/images/dependency_graph.svg)

gday/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "gday"
 version = "0.1.1"
-description = "Command line tool to send files easily, securely, and directly, without a relay or port forwarding."
+description = "Command line tool to send files directly and securely, without a relay or port forwarding."
 homepage = "https://github.com/manforowicz/gday/gday/"
 
 # Inherit these keys from workspace toml
@@ -13,8 +13,7 @@ repository.workspace = true
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-anyhow = "1.0.86"
-clap = { version = "4.5.4", features = ["derive"] }
+clap = { version = "4.5.6", features = ["derive"] }
 env_logger = "0.11.3"
 gday_encryption = { version = "0.1.1", path = "../gday_encryption" }
 gday_file_transfer = { version = "0.1.1", path = "../gday_file_transfer" }
@@ -23,7 +22,6 @@ indicatif = "0.17.8"
 log = "0.4.21"
 os_str_bytes = "7.0.0"
 owo-colors = "4.0.0"
-postcard = "1.0.8"
 rand = "0.8.5"
 serde = { version = "1.0.203", features = ["serde_derive"] }
-thiserror = "1.0.61"
+thiserror = "1.0.61"

gday/README.md

@@ -1,3 +1,5 @@
+Note: this crate is still in early-development, so expect breaking changes.
+
 # `gday`
 ![Crates.io Version](https://img.shields.io/crates/v/gday) ![docs.rs](https://img.shields.io/docsrs/gday)
 

gday/src/main.rs

@@ -1,3 +1,5 @@
+//! Note: this crate is still in early-development, so expect breaking changes.
+//!
 //! `gday` is a command line line tool for peers to send each other files.
 //! Features:
 //! - Never uses relays. Instead, uses a gday_contact_exchange_server to share socket

gday_contact_exchange_protocol/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "gday_contact_exchange_protocol"
 version = "0.1.1"
-description = "Protocol that peers can use to exchange their public and private socket addresses via a server."
+description = "Protocol for peers to exchange their socket addresses via a server."
 homepage = "https://github.com/manforowicz/gday/gday_contact_exchange_protocol/"
 
 # Inherit these keys from workspace toml

gday_contact_exchange_protocol/README.md

@@ -1,3 +1,5 @@
+Note: this crate is still in early-development, so expect breaking changes.
+
 # `gday_contact_exchange_protocol`
 ![Crates.io Version](https://img.shields.io/crates/v/gday_contact_exchange_protocol) ![docs.rs](https://img.shields.io/docsrs/gday_contact_exchange_protocol)
 

gday_contact_exchange_protocol/src/lib.rs

@@ -1,3 +1,5 @@
+//! Note: this crate is still in early-development, so expect breaking changes.
+//!
 //! This protocol lets two users exchange their public and (optionally) private socket addresses via a server.
 //!
 //! On it's own, this crate doesn't do anything other than define a shared protocol.

gday_encryption/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "gday_encryption"
 version = "0.1.1"
-description = "A simple ChaCha20Poly1305 encryption wrapper around an IO stream."
+description = "Minimal ChaCha20Poly1305 encryption wrapper around an IO stream."
 homepage = "https://github.com/manforowicz/gday/gday_encryption/"
 
 # Inherit these keys from workspace toml

gday_encryption/README.md

@@ -1,3 +1,5 @@
+Note: this crate is still in early-development, so expect breaking changes.
+
 # `gday_encryption`
 ![Crates.io Version](https://img.shields.io/crates/v/gday_encryption) ![docs.rs](https://img.shields.io/docsrs/gday_encryption)
 

gday_encryption/src/lib.rs

@@ -1,3 +1,5 @@
+//! Note: this crate is still in early-development, so expect breaking changes.
+//!
 //! A simple encrypted wrapper around an IO stream.
 //! Uses [`chacha20poly1305`] with the [`chacha20poly1305::aead::stream`].
 #![forbid(unsafe_code)]

gday_file_transfer/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "gday_file_transfer"
 version = "0.1.1"
-description = "A minimal protocol to securely transfer files over an IO stream. Used by gday."
+description = "Protocol to securely transfer files over an encrypted IO stream."
 homepage = "https://github.com/manforowicz/gday/gday_file_transfer/"
 
 # Inherit these keys from workspace toml

gday_file_transfer/README.md

@@ -1,3 +1,5 @@
+Note: this crate is still in early-development, so expect breaking changes.
+
 # `gday_file_offer_protocol`
 ![Crates.io Version](https://img.shields.io/crates/v/gday_file_offer_protocol) ![docs.rs](https://img.shields.io/docsrs/gday_file_offer_protocol)