refactoring to execute commands

metallkopf · Oct 28, 2024 · ae5067e · ae5067e
1 parent 7efac67
commit ae5067e
Show file tree

Hide file tree

Showing 8 changed files with 545 additions and 206 deletions.
diff --git a/README.md b/README.md
@@ -1,11 +1,16 @@
 # Konnect - headless kde connect
+
 Konnect is based on the [KDE Connect](https://community.kde.org/KDEConnect) protocol and allows a non-interactive enviroment (headless server) to send notifications to your devices via Rest API or a *simple* CLI
 
+> Warning: Breaking chanches between versions 0.1.x and 0.2.x on the client tool and rest api.
+
 ## Prerequisites
+
 - Python 3.10+
 - Systemd (optional)
 
 ## Installation
+
 ```bash
 # Create virtualenv
 python3 -m venv venv
@@ -20,86 +25,20 @@ venv/bin/pip install https://github.com/metallkopf/konnect/releases/download/0.2
 venv/bin/pip install git+https://github.com/metallkopf/konnect.git@master#egg=konnect
 ```
 
-## Test run
-```bash
-# With KDE Connect installed
-venv/bin/konnectd --name Test --admin-port 8080
+## Server
 
-# Without KDE Connect installed
-venv/bin/konnectd --name Test --receiver --admin-port 8080
-```
+### Server options
 
-## Examples
-- List available devices
-```bash
-# Rest API
-curl -s -X GET http://localhost:8080/device
-
-# CLI
-venv/bin/konnect devices
-{
-  "devices": [
-    {
-      "identifier": "00112233_4455_6677_8899-aabbccddeeff",
-      "name": "server",
-      "trusted": true,
-      "reachable": true
-    },
-    {
-      "identifier": "abcdef0123456789",
-      "name": "phone",
-      "trusted": false,
-      "reachable": true
-    }
-  ],
-  "success": true
-}
-```
-- Pair with device
-```bash
-# Rest API
-curl -s -X POST http://localhost:8080/pair/@phone
-
-# CLI
-venv/bin/konnect pair --device @phone
-```
-- Accept pairing request on remote host
-- Check successful pairing by sending ping
-```bash
-# Rest API
-curl -s -X POST http://localhost:8080/ping/@phone
-
-# CLI
-venv/bin/konnect ping --device @phone
-```
-- Send notification
-```bash
-# Rest API
-curl -s -X POST -d '{"application":"Package Manager","title":"Maintenance","text":"There are updates available!","reference":"update"}' http://localhost:8080/notification/@phone
-
-# CLI
-venv/bin/konnect notification --device @phone --title maintenance --text "updates available" --application package_manager --reference update
-```
-- Unpair device
-```bash
-# Rest API
-curl -s -X DELETE http://localhost:8080/pair/@phone
-
-# CLI
-venv/bin/konnect unpair --unpair @phone
-```
-
-## Daemon usage
 ```bash
 venv/bin/konnectd --help
 ```
+
 ```
-usage: konnectd [--name NAME] [--debug] [--discovery-port PORT] [--service-port PORT] [--transfer-port PORT]
-                [--max-transfer-ports NUM] [--admin-port PORT] [--admin-socket SOCK] [--admin-bind BIND]
-                [--config-dir DIR] [--receiver] [--service] [--help] [--version]
+usage: konnectd [--name NAME] [--debug] [--discovery-port PORT] [--service-port PORT] [--transfer-port PORT] [--max-transfer-ports NUM] [--admin-port PORT] [--admin-socket SOCK] [--admin-bind BIND] [--config-dir DIR]
+                [--receiver] [--service] [--help] [--version]
 
 options:
-  --name NAME           Device name (default: computer)
+  --name NAME           Device name (default: HOSTNAME)
   --debug               Show debug messages (default: False)
   --discovery-port PORT
                         Discovery port (default: 1716)
@@ -117,42 +56,102 @@ options:
   --version             Version information (default: False)
 ```
 
-## Rest API
+### Test run
+
+```bash
+# With KDE Connect installed (admin interface by default on port 8080)
+venv/bin/konnectd --name Test
+
+# With KDE Connect installed (socket by default on ${XDG_RUNTIME_DIR}/konnectd.sock)
+venv/bin/konnectd --name Test --admin-bind socket
+
+# Without KDE Connect installed (listen for announce)
+venv/bin/konnectd --name Test --receiver
+```
+
+### Run as service
+
+Create a file named `konnect.service` in `/etc/systemd/system`, change the value `User` and `WorkingDirectory` accordingly and the execute the following commands
+
+```ini
+[Unit]
+Description=Konnect
+After=network.target
+Requires=network.target
+
+[Service]
+User=user
+Restart=always
+Type=simple
+WorkingDirectory=/home/user/konnect
+ExecStart=/home/user/konnect/venv/bin/konnectd --receiver --service
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+# Reload configurations
+sudo systemctl daemon-reload
+
+# Start service
+sudo systemctl start konnect
+
+# Start on boot
+sudo systemctl enable konnect
+```
+
+### Rest API
+
 | Method | Resource | Description | Parameters |
 | - | - | - | - |
 | GET | / | Application info | |
 | PUT | / | Announce identity | |
-| GET | /device | List devices | |
+| GET | /command | List all \(local\) commands | |
+| GET | /command/\(@name\|identifier\) | List device commands | |
+| POST | /command/\(@name\|identifier\) | Add device command | name, command |
+| DELETE | /command/\(@name\|identifier\) | Remove all device commands | |
+| PUT | /command/\(@name\|identifier\)/\(key\) | Update device command | name, command |
+| DELETE | /command/\(@name\|identifier\)/\(key\) | Remove device command | |
+| PATCH | /command/\(@name\|identifier\)/\(key\) | Execute \(remote\) device command | |
+| POST | /custom/\(@name\|identifier\) | Custom packet \(for testing only\) | type, body \(optional\) |
+| GET | /device | List all devices | |
 | GET | /device/\(@name\|identifier\) | Device info | |
-| GET | /command | List all commands | |
+| GET | /notification | List all notifications | |
 | POST | /notification/\(@name\|identifier\) | Send notification | text, title, application, reference \(optional\), icon \(optional\) |
 | DELETE | /notification/\(@name\|identifier\)/\(reference\) | Cancel notification | |
 | POST | /pair/\(@name\|identifier\) | Pair | |
 | DELETE | /pair/\(@name\|identifier\) | Unpair | |
 | POST | /ping/\(@name\|identifier\) | Ping device | |
 | POST | /ring/\(@name\|identifier\) | Ring device | |
-| POST | /custom/\(@name\|identifier\) | Custom packet \(for testing only\) | type, body \(optional\) |
 
-## CLI usage
+## Client
+
+This utility can be used alone but requires the packages `requests` and `PIL` to work.
+
+### Client usage
+
 ```bash
-venv/bin/konnect help
+./venv/bin/konnect help
 ```
+
 ```
-usage: konnect [--port PORT] [--debug]
-               {announce,custom,device,devices,exec,notification,pair,ping,ring,unpair,version,help}
-               ...
+usage: konnect [--port PORT] [--debug] {announce,command,commands,custom,devices,exec,info,notifications,notification,pair,ping,ring,unpair,version,help} ...
 
 options:
   --port PORT           Port running the admin interface
   --debug               Show debug messages
 
 actions:
-  {announce,custom,device,devices,exec,notification,pair,ping,ring,unpair,version,help}
+  {announce,command,commands,custom,devices,exec,info,notifications,notification,pair,ping,ring,unpair,version,help}
     announce            Announce your identity
+    command             Configure local commands...
+    commands            List all commands...
     custom              Send custom packet...
-    device              Show device info
-    devices             List devices
+    devices             List all devices...
     exec                Execute remote command...
+    info                Show server info
+    notifications       List all notifications...
     notification        Send or cancel notification...
     pair                Pair with device...
     ping                Send ping...
@@ -162,46 +161,106 @@ actions:
     help                This
 ```
 
-## Run as service
-Create a file named `konnect.service` in `/etc/systemd/system`, change the value `User` and `WorkingDirectory` accordingly and the execute the following commands
-```ini
-[Unit]
-Description=Konnect
-After=network.target
-Requires=network.target
+### List devices
 
-[Service]
-User=user
-Restart=always
-Type=simple
-WorkingDirectory=/home/user/konnect
-ExecStart=/home/user/konnect/venv/bin/konnectd --receiver --service
+```bash
+./venv/bin/konnect devices
+```
 
-[Install]
-WantedBy=multi-user.target
+```yaml
+devices:
+- identifier: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+  name: computer
+  type: desktop
+  reachable: true
+  trusted: true
+  commands:
+    00112233-4455-6677-8899-aabbccddeeff:
+      name: kernel
+      command: uname -a
+    550e8400-e29b-41d4-a716-446655440000:
+      name: who
+      command: whoami
+- identifier: 9c5b94b1-35ad-49bb-b118-8e8fc24abf80
+  name: phone
+  type: smartphone
+  reachable: false
+  trusted: true
+  commands: {}
 ```
+
+### Pair device
+
 ```bash
-# Reload configurations
-sudo systemctl daemon-reload
+./venv/bin/konnect pair --device @computer
+```
 
-# Start service
-sudo systemctl start konnect
+### Ping device
 
-# Start on boot
-sudo systemctl enable konnect
+```bash
+./venv/bin/konnect ping --device @computer
+```
+
+### Send notification
+
+```bash
+./venv/bin/konnect notification --device @computer --application "Package Manager" \
+  --title Maintenance --text "There are updates available!" --reference update
+```
+
+```yaml
+key: update
 ```
 
-## Compatibility
-Tested *manually* on [kdeconnect](https://invent.kde.org/kde/kdeconnect-kde) 1.3.3+ and [kdeconnect-android](https://f-droid.org/en/packages/org.kde.kdeconnect_tp/) 1.13.0+
+### Dismiss notification
+
+```bash
+./venv/bin/konnect notification --device @computer --reference update --delete
+```
+
+### Execute (remote) command
+
+```bash
+./venv/bin/konnect exec --device @computer --key 00112233-4455-6677-8899-aabbccddeeff
+```
+
+### Add (local) command
+
+```bash
+./venv/bin/konnect command --device @computer --name "reboot" --command "sudo reboot"
+```
+
+```yaml
+key: 03000200-0400-0500-0006-000700080009
+```
+
+### List (local) commands
+
+```bash
+./venv/bin/konnect commands
+```
+
+```yaml
+- identifier: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+  device: computer
+  key: 03000200-0400-0500-0006-000700080009
+  name: reboot
+  command: sudo reboot
+```
 
 ## Troubleshooting
+
 ### Read how to open firewall ports on
+
 - [KDE Connect\'s wiki](https://community.kde.org/KDEConnect#Troubleshooting)
+
 ### Installation errors (required OS packages)
+
 - Debian-based: `sudo apt-get install libsystemd-dev pkg-config python3-venv`
 - RedHat-like: `sudo dnf install gcc pkg-config python3-devel systemd-devel`
 
 ## To-do (in no particular order)
+
 - Unit testing
 - Periodically announce identity
 - Connect to devices instead of just listening
@@ -211,10 +270,10 @@ Tested *manually* on [kdeconnect](https://invent.kde.org/kde/kdeconnect-kde) 1.3
 - MDNS support?
 - Share an receive files?
 
-## Contributor(s)
-- coxtor
+## Development
+
+### Code Style
 
-## Code Style
 ```bash
 venv/bin/isort --diff konnect/*.py
 
@@ -223,12 +282,18 @@ venv/bin/flake8 konnect/*.py
 venv/bin/pytest -vv
 ```
 
-## Releasing
+### Releasing
+
 ```bash
 venv/bin/python -m build --wheel
 
 venv/bin/twine check dist/*
 ```
 
+## Contributor(s)
+
+- coxtor
+
 ## License
+
 [GPLv2](https://www.gnu.org/licenses/gpl-2.0.html)
diff --git a/konnect/__init__.py b/konnect/__init__.py
@@ -1 +1 @@
-__version__ = "0.1.6"
+__version__ = "0.2.0"