Sign in to a server and share swarms through it

Cargo.toml

@@ -66,7 +66,7 @@ serde = { version = "1.0.229", features = ["derive"] }
 serde_json = "1.0.151"
 confy = "2.0.0"
 clap_complete = "4.6.9"
-tokio = "1.53.1"
+tokio = { version = "1.53.1", features = ["net", "io-util", "time"] }
 serde_yaml = "0.9.34"
 probe-rs = "0.32.0"
 clap-num = "1.2.0"
@@ -84,6 +84,10 @@ byteorder = "1.5.0"
 hex = "0.4.3"
 chrono = "0.4.45"
 tabled = "0.22.0"
+base64 = "0.22"
+sha2 = "0.11"
+gethostname = "1"
+open = "5"
 
 [target.'cfg(unix)'.dependencies]
 crazyflie-lib = { version = "0.8.2", default-features = false, features = ["packet_capture"] }

README.md

@@ -87,6 +87,7 @@ Commands:
   lh           Lighthouse positioning system configuration
   deck         Decks attached to the Crazyflie
   swarm        Swarms of Crazyflies: store them and run commands on them
+  auth         Your account for sharing swarms: sign in, sign out
   completions  Generate a shell completion script (printed to stdout)
   help         Print this message or the help of the given subcommand(s)
 
@@ -198,6 +199,7 @@ For a more indepth view on how to use the different commands, have a look at the
 * [Select](/docs/select.md)
 * [Settings](/docs/settings.md)
 * [Swarms](/docs/swarm.md)
+* [Signing in](/docs/auth.md)
 * [Crazyradio](/docs/crazyradio.md)
 * [Debug](/docs/debug.md)
 * [Test](/docs/test.md)

docs/auth.md

@@ -0,0 +1,66 @@
+# Signing in
+
+The `auth` command signs cfcli in to the server that shares swarms between
+cfcli, Swarmkeeper and the people you fly with. Signing in is optional:
+everything else in cfcli works without it.
+
+```text
+Usage: cfcli auth <COMMAND>
+
+Commands:
+  login   Sign in through the browser; cfcli gets its key by itself
+  logout  Sign out and revoke cfcli's key
+  status  Show who cfcli is signed in as
+  help    Print this message or the help of the given subcommand(s)
+```
+
+## Sign in
+
+```bash
+cfcli auth login
+```
+
+cfcli opens the sign-in page in your browser. Sign in with GitHub or Google if
+you aren't already, and allow "cfcli on <computer>". The browser hands the
+key back to cfcli by itself; there is nothing to copy. The page then says you
+can close the tab.
+
+If the browser doesn't open, cfcli prints the link to open instead. Open it in
+a browser on the same computer: the browser returns the key to cfcli over
+`127.0.0.1`. `--no-browser` only prints the link.
+
+`--server` signs in to another server, such as one on your own network:
+
+```bash
+cfcli auth login --server http://lab-server:3000
+```
+
+Signing in again replaces the previous sign-in and revokes its key.
+
+## Show who cfcli is signed in as
+
+```bash
+cfcli auth status
+```
+
+Prints the server, your name, the key's name and the organizations your swarms
+are shared in. When cfcli isn't signed in, or the key no longer works, it says
+so and exits with code 20.
+
+## Sign out
+
+```bash
+cfcli auth logout
+```
+
+Revokes cfcli's key on the server and forgets it.
+
+## The key
+
+cfcli signs in with an API key of its own, named "cfcli on &lt;computer&gt;". It
+reads and uploads swarms as you in the organizations you are a member of. It
+is listed on the server's API keys page, where you can revoke it; that signs
+cfcli out too.
+
+The key is stored in `credentials.json` in the cfcli config folder (next to
+the `swarms` folder, see `cfcli settings show`), readable only by you.

docs/settings.md

@@ -11,6 +11,7 @@ Commands:
   show     Show all current settings
   timeout  Manage the connection timeout
   address  Manage scan addresses
+  sync     Whether swarm commands sync shared swarms with the server
   help     Print this message or the help of the given subcommand(s)
 ```
 
@@ -90,3 +91,17 @@ If all addresses are removed, the list is automatically reset to the default
 ```bash
 cfcli settings address clear
 ```
+
+## Syncing shared swarms
+
+Whether swarm commands check the server before using a [shared swarm](swarm.md#sharing-swarms)
+and upload changes right away (on, the default), or use this computer's copies
+so they run faster (off). With sync off, `cfcli swarm config pull` and `push`
+sync the copies.
+
+```bash
+cfcli settings sync show
+cfcli settings sync off
+cfcli settings sync on
+```
+

docs/swarm.md

@@ -20,14 +20,15 @@ cfcli swarm config list
 ```
 
 ```text
-  | ID   | Name           | Crazyflies
---+------+----------------+------------
-* | lab  | Lab Crazyflies | 3
-  | show | Show swarm     | 49
+  | ID   | Name           | Crazyflies | Stored
+--+------+----------------+------------+---------------
+* | lab  | Lab Crazyflies | 3          | this computer
+  | show | Show swarm     | 49         | this computer
 ```
 
 The ID (`lab`) is what you type in commands. It is also the file name, so it
 can only contain letters, digits, `-`, `_` and `.`. The name is only shown.
+Shared swarms (see [Sharing swarms](#sharing-swarms)) are listed too.
 
 Select another swarm by ID, or run `select` without an ID to pick one from a
 list. When running non-interactively, `select` without an ID prints the list
@@ -144,6 +145,70 @@ cfcli swarm config export
 cfcli swarm config export lab -o lab.yaml
 ```
 
+## Sharing swarms
+
+When cfcli is [signed in](auth.md), swarms can be shared with the people you
+fly with through the server. A shared swarm's ID is `<organization>/<swarm>`,
+for instance `bitcraze-lab/cage`; a local swarm's is just `<swarm>`. Every swarm
+command takes either, and `list` shows both:
+
+```text
+  | ID                | Name        | Crazyflies | Stored
+--+-------------------+-------------+------------+----------------------------
+* | lab               | Lab         | 3          | this computer
+  | bitcraze-lab/cage | Flight cage | 8          | arc.bitcraze.io, revision 3
+```
+
+Create a shared swarm, change it like any other, and delete it (for everyone
+in the organization):
+
+```bash
+cfcli swarm config create bitcraze-lab/demo --name "Demo"
+cfcli swarm config add radio:///80/2M/E7E7E7E701 --name CF-01 --swarm bitcraze-lab/demo
+cfcli swarm config delete bitcraze-lab/demo
+```
+
+Share a local swarm by moving it to the server, and move it back to stop
+sharing it. Moving it back deletes it on the server, so cfcli asks first. The
+selected swarm follows the move:
+
+```bash
+cfcli swarm config move lab bitcraze-lab/lab
+cfcli swarm config move bitcraze-lab/lab lab
+```
+
+`move` also renames a swarm (`move lab lab-old`). `import` can put a file
+straight into a shared swarm with `--id bitcraze-lab/<swarm>`.
+
+### Sync
+
+cfcli keeps a copy of each shared swarm it uses. With sync on, which is the
+default, every command checks the server first (a quick check when nothing
+changed) and changes go to the server right away. If someone else changed the
+swarm in the meantime, your change is made again on their version, so nobody's
+work is lost.
+
+Turn sync off to make commands faster; they then use this computer's copies,
+and you sync them yourself:
+
+```bash
+cfcli settings sync off
+cfcli swarm config pull          # get the latest version of every shared swarm
+cfcli swarm config push          # upload the changes made here
+```
+
+`list` marks copies with changes that aren't pushed. When someone else changed
+a swarm since your copy, `push` stops and tells you how to choose: `pull
+--force <swarm>` keeps their version and drops yours, `push --force <swarm>`
+keeps yours and overwrites theirs. `pull` never drops changes that aren't
+pushed unless you give `--force`.
+
+When the server can't be reached, commands use the copies and say so, and
+changes are kept: with sync on they are uploaded when the server answers
+again, with sync off by `push`. Working with the Crazyflies never waits for
+the internet. Creating and deleting shared swarms needs the server, except
+that a swarm created without it is uploaded later.
+
 ## Any Crazyradio
 
 Leaving the radio in a URI empty means any Crazyradio:
@@ -420,6 +485,11 @@ Swarms are files in a `swarms` folder next to the cfcli config file, on Linux
 `~/.config/cf-cli/swarms/<id>.yaml`. `cfcli settings show` prints the folder
 and the selected swarm. Use `import` and `export` rather than editing the files.
 
+The copies of shared swarms are kept apart from them, in
+`~/.config/cf-cli/synced/<server>/<organization>/<swarm>.yaml`, with
+`state.json` saying which revision each copy is and whether it has changes
+that aren't pushed. Don't edit those; change shared swarms with the commands.
+
 ### File format
 
 ```yaml