[feature] Added Mass Command model and REST API #1344

Closes #1344

---------

Co-authored-by: Federico Capoano <f.capoano@openwisp.io>

Author: dee077

docs/developer/extending.rst

@@ -354,6 +354,7 @@ Once you have created the models, add the following to your
     CONNECTION_CREDENTIALS_MODEL = "sample_connection.Credentials"
     CONNECTION_DEVICECONNECTION_MODEL = "sample_connection.DeviceConnection"
     CONNECTION_COMMAND_MODEL = "sample_connection.Command"
+    CONNECTION_BATCHCOMMAND_MODEL = "sample_connection.BatchCommand"
     SUBNET_DIVISION_SUBNETDIVISIONRULE_MODEL = "sample_subnet_division.SubnetDivisionRule"
     SUBNET_DIVISION_SUBNETDIVISIONINDEX_MODEL = "sample_subnet_division.SubnetDivisionIndex"
 

docs/user/intro.rst

@@ -70,6 +70,9 @@ e.g.:
 
 - Sending configuration updates.
 - :doc:`Executing shell commands <shell-commands>`.
+- :doc:`Executing mass commands <shell-commands>`: Run a command on
+  multiple devices at once, see the :ref:`batch command API
+  <controller_batch_command_api>` for details.
 - Perform firmware upgrades via the additional :doc:`firmware upgrade
   module </firmware-upgrader/index>`.
 

docs/user/rest-api.rst

@@ -210,7 +210,7 @@ config of a device,
 
     curl -X PATCH \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "config": {
@@ -225,7 +225,7 @@ the/their {id} from the config of a device,
 
     curl -X PATCH \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "config": {
@@ -240,7 +240,7 @@ from the config of a device,
 
     curl -X PATCH \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'cache-control: no-cache' \
         -H 'content-type: application/json' \
         -H 'postman-token: b3f6a1cc-ff13-5eba-e460-8f394e485801' \
@@ -465,7 +465,7 @@ command type being executed.
 
     curl -X POST \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/command/ \
-        -H 'authorization: Bearer yoursecretauthtoken' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "type": "custom",
@@ -481,6 +481,117 @@ Get Command Details
 
     GET /api/v1/controller/device/{device_id}/command/{command_id}/
 
+.. _controller_batch_command_api:
+
+Dry-Run Mass Command
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    GET /api/v1/controller/batch-command/execute/
+
+Returns the list of devices that would be targeted without executing
+anything. Useful for previewing which devices are affected.
+
+**Query Parameters:**
+
+================ =========================================================
+Parameter        Description
+================ =========================================================
+``organization`` Organization UUID (optional for superusers; set
+                 automatically when ``group`` or ``location`` is provided)
+``type``         Command type (optional for dry-run)
+``input``        JSON input data for the command (optional for dry-run).
+                 Encode as a URL-encoded JSON object, e.g.
+                 ``?type=custom&input=%7B%22command%22%3A%22uptime%22%7D``
+``devices``      Repeated ``devices`` query parameter, each a device UUID
+                 (optional; when provided, ``group`` and ``location`` are
+                 ignored)
+``group``        Device group UUID (optional)
+``location``     Location UUID (optional)
+================ =========================================================
+
+Execute a Mass Command
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    POST /api/v1/controller/batch-command/execute/
+
+Creates and executes a batch command on the targeted devices.
+
+**Request Parameters:**
+
+================ =========================================================
+Parameter        Description
+================ =========================================================
+``organization`` Organization UUID (optional for superusers; set
+                 automatically when ``group`` or ``location`` is provided)
+``type``         Type of command to execute (**required**)
+``input``        Input data for the command (**conditionally required** —
+                 depends on command type)
+``label``        A short label to identify this batch command
+                 (**required**)
+``notes``        Optional notes (optional)
+``devices``      List of device UUIDs (optional; when provided, ``group``
+                 and ``location`` are ignored)
+``group``        Device group UUID (optional)
+``location``     Location UUID (optional)
+================ =========================================================
+
+**Available Command Types:**
+
+See :ref:`controller_execute_command_api` for available command types and
+input formats.
+
+**Example payload:**
+
+.. code-block:: json
+
+    {
+        "organization": "org-uuid",
+        "type": "custom",
+        "input": {"command": "uptime"},
+        "label": "Check uptime"
+    }
+
+**Example request:**
+
+.. code-block:: shell
+
+    curl -X POST \
+        http://127.0.0.1:8000/api/v1/controller/batch-command/execute/ \
+        -H 'authorization: Bearer <token>' \
+        -H 'content-type: application/json' \
+        -d '{
+                "organization": "org-uuid",
+                "type": "custom",
+                "input": {"command": "uptime"},
+                "label": "Check uptime"
+            }'
+
+**Response:** ``201 Created`` with the batch command UUID.
+
+List Mass Commands
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    GET /api/v1/controller/batch-command/
+
+Returns a paginated list of batch commands with device count and skipped
+device information.
+
+Get Mass Command Detail
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    GET /api/v1/controller/batch-command/{id}/
+
+Returns detailed information about a batch command, including the list of
+targeted devices.
+
 List Device Groups
 ~~~~~~~~~~~~~~~~~~
 
@@ -603,7 +714,7 @@ You can create ``DeviceLocation`` object by using primary keys of existing
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
             "location": "f0cb5762-3711-4791-95b6-c2f6656249fa",
@@ -635,7 +746,7 @@ single request.
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "location": {
@@ -686,7 +797,7 @@ demonstrates creating both ``Location`` and ``FloorPlan`` objects.
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
         -F 'location.name=Via del Corso' \
         -F 'location.address=Via del Corso, Roma, Italia' \
@@ -716,7 +827,7 @@ plan for that location using this endpoint.
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
         -F location=f0cb5762-3711-4791-95b6-c2f6656249fa \
         -F floorplan.floor=1 \
@@ -907,7 +1018,7 @@ in a single request.
 
     curl -X POST \
         http://127.0.0.1:8000/api/v1/controller/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
         -F 'name=Via del Corso' \
         -F 'address=Via del Corso, Roma, Italia' \

docs/user/shell-commands.rst

@@ -182,3 +182,36 @@ How to register or unregister commands
 
 Refer to :ref:`registering_unregistering_commands` in the developer
 documentation.
+
+.. _mass_commands:
+
+Mass Commands
+-------------
+
+Mass commands allow you to execute a command on multiple devices
+simultaneously, rather than issuing commands one device at a time. This is
+useful for rebooting all devices in a group, changing passwords across
+multiple devices, or running diagnostics on all devices in an
+organization.
+
+**Targeting options:**
+
+- ``organization``: All devices in an organization.
+- ``devices``: Explicit list of device UUIDs.
+- ``group``: Device group UUID.
+- ``location``: Location UUID.
+
+If ``devices`` is provided, ``group`` and ``location`` are ignored.
+Otherwise, ``group`` and ``location`` can be used together to narrow the
+target set within the organization.
+
+If no targeting options are provided, the command targets all devices in
+the organization. Superusers can omit ``organization`` to target all
+devices across organizations.
+
+For superusers, ``organization`` is set automatically when ``group`` or
+``location`` is provided.
+
+Refer to the :ref:`Batch Command API <controller_batch_command_api>`
+documentation for the available endpoints, request parameters, and
+examples.

openwisp_controller/connection/api/serializers.py

@@ -12,6 +12,7 @@
 DeviceConnection = load_model("connection", "DeviceConnection")
 Credentials = load_model("connection", "Credentials")
 Device = load_model("config", "Device")
+BatchCommand = load_model("connection", "BatchCommand")
 
 
 class ValidatedDeviceFieldSerializer(ValidatedModelSerializer):
@@ -43,6 +44,10 @@ class CommandSerializer(ValidatedDeviceFieldSerializer):
         required=False,
         pk_field=serializers.UUIDField(format="hex_verbose"),
     )
+    batch_command = serializers.PrimaryKeyRelatedField(
+        read_only=True,
+        pk_field=serializers.UUIDField(format="hex_verbose"),
+    )
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -115,3 +120,118 @@ class Meta:
             "is_working": {"read_only": True},
         }
         read_only_fields = ("created", "modified")
+
+
+class BatchCommandExecuteSerializer(
+    FilterSerializerByOrgManaged, serializers.ModelSerializer
+):
+    """
+    Parses batch command input.
+
+    It does not save data, so it does not need ValidatedModelSerializer.
+    BatchCommand.execute() and dry_run() validate the model.
+    """
+
+    input = serializers.JSONField(allow_null=True, required=False)
+    devices = serializers.PrimaryKeyRelatedField(
+        many=True,
+        queryset=Device.objects.all(),
+        required=False,
+        allow_empty=True,
+        pk_field=serializers.UUIDField(format="hex_verbose"),
+    )
+
+    def __init__(self, *args, dry_run=False, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.dry_run = dry_run
+        if dry_run:
+            self.fields["type"].required = False
+            self.fields["label"].required = False
+
+    class Meta:
+        model = BatchCommand
+        fields = (
+            "organization",
+            "type",
+            "input",
+            "label",
+            "notes",
+            "devices",
+            "group",
+            "location",
+        )
+        extra_kwargs = {
+            "organization": {"required": False, "allow_null": True},
+        }
+
+    def validate(self, data):
+        org = data.get("organization")
+        if not org and not self.context["request"].user.is_superuser:
+            raise serializers.ValidationError(
+                _("Only superusers can execute batch commands without an organization.")
+            )
+        # DRF's many=True injects [] for QueryDict even when key is
+        # absent; remove it so model can distinguish omitted vs explicit [].
+        if "devices" not in self.initial_data and "devices" in data:
+            data.pop("devices")
+        return data
+
+
+class BatchCommandSerializer(BaseSerializer):
+    device_count = serializers.IntegerField(read_only=True)
+    skipped_devices = serializers.JSONField(read_only=True)
+    organization = serializers.PrimaryKeyRelatedField(
+        read_only=True,
+        pk_field=serializers.UUIDField(format="hex_verbose"),
+    )
+    group = serializers.PrimaryKeyRelatedField(
+        read_only=True,
+        allow_null=True,
+        pk_field=serializers.UUIDField(format="hex_verbose"),
+    )
+    location = serializers.PrimaryKeyRelatedField(
+        read_only=True,
+        allow_null=True,
+        pk_field=serializers.UUIDField(format="hex_verbose"),
+    )
+
+    def to_representation(self, instance):
+        data = super().to_representation(instance)
+        # The raw password is visible in API responses between
+        # when the batch is saved and when the Celery task runs _clean_sensitive_info().
+        if instance.type == "change_password":
+            data["input"] = {"password": "********"}
+        return data
+
+    class Meta:
+        model = BatchCommand
+        fields = (
+            "id",
+            "organization",
+            "status",
+            "type",
+            "input",
+            "label",
+            "notes",
+            "group",
+            "location",
+            "device_count",
+            "skipped_devices",
+            "created",
+            "modified",
+        )
+        read_only_fields = (
+            "created",
+            "modified",
+        )
+
+
+class BatchCommandDetailSerializer(BatchCommandSerializer):
+    devices = serializers.PrimaryKeyRelatedField(
+        many=True,
+        read_only=True,
+        pk_field=serializers.UUIDField(format="hex_verbose"),
+    )
+
+    class Meta(BatchCommandSerializer.Meta):
+        fields = BatchCommandSerializer.Meta.fields + ("devices",)