[feature] BatchCommand model and REST APIs for async batch command execution

docs/user/rest-api.rst

@@ -481,6 +481,115 @@ Get Command Details
 
     GET /api/v1/controller/device/{device_id}/command/{command_id}/
 
+.. _controller_batch_command_api:
+
+Dry-Run Batch 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)
+``type``         Command type (optional for dry-run)
+``input``        Input data for the command (optional for dry-run)
+``devices``      Repeated ``devices`` query parameter, each a device UUID
+                 (optional)
+``group``        Device group UUID (optional)
+``location``     Location UUID (optional)
+``execute_all``  Set to ``true`` to target all devices (optional)
+================ ========================================================
+
+Execute a Batch 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)
+``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)
+``group``        Device group UUID (optional)
+``location``     Location UUID (optional)
+``execute_all``  Set to ``true`` to target all devices (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",
+        "execute_all": true
+    }
+
+**Example request:**
+
+.. code-block:: shell
+
+    curl -X POST \
+        http://127.0.0.1:8000/api/v1/controller/batch-command/execute/ \
+        -H 'authorization: Bearer yoursecretauthtoken' \
+        -H 'content-type: application/json' \
+        -d '{
+                "organization": "org-uuid",
+                "type": "custom",
+                "input": {"command": "uptime"},
+                "label": "Check uptime",
+                "execute_all": true
+            }'
+
+**Response:** ``201 Created`` with the batch command UUID.
+
+List Batch 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 Batch 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
 ~~~~~~~~~~~~~~~~~~
 

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,117 @@ class Meta:
             "is_working": {"read_only": True},
         }
         read_only_fields = ("created", "modified")
+
+
+class BatchCommandExecuteSerializer(
+    FilterSerializerByOrgManaged, serializers.ModelSerializer
+):
+    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"),
+    )
+    execute_all = serializers.BooleanField(required=False, default=False)
+
+    def __init__(self, *args, dry_run=False, **kwargs):
+        super().__init__(*args, **kwargs)
+        if dry_run:
+            self._skip_target_validation = True
+            self.fields["type"].required = False
+            self.fields["label"].required = False
+        else:
+            self._skip_target_validation = False
+
+    class Meta:
+        model = BatchCommand
+        fields = (
+            "organization",
+            "type",
+            "input",
+            "label",
+            "notes",
+            "devices",
+            "group",
+            "location",
+            "execute_all",
+        )
+        extra_kwargs = {
+            "organization": {"required": False, "allow_null": True},
+        }
+
+    def validate(self, data):
+        org = data.get("organization")
+        execute_all = data.get("execute_all", False)
+        devices = data.get("devices")
+        group = data.get("group")
+        location = data.get("location")
+        if not org and not self.context["request"].user.is_superuser:
+            raise serializers.ValidationError(
+                _("Only superusers can execute batch commands without an organization.")
+            )
+        if not self._skip_target_validation:
+            if (
+                not execute_all
+                and not org
+                and not devices
+                and not group
+                and not location
+            ):
+                raise serializers.ValidationError(
+                    _(
+                        "Specify at least one targeting option "
+                        "or set execute_all to true."
+                    )
+                )
+        if devices:
+            for device in devices:
+                if org and device.organization_id != org.id:
+                    raise serializers.ValidationError(
+                        {
+                            "devices": _(
+                                "All devices must belong to the same organization."
+                            )
+                        }
+                    )
+        return data
+
+
+class BatchCommandSerializer(BaseSerializer):
+    device_count = serializers.IntegerField(read_only=True)
+    skipped_devices = serializers.JSONField(read_only=True)
+
+    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",)

openwisp_controller/connection/api/urls.py

@@ -40,6 +40,21 @@ def get_api_urls(api_views):
             api_views.deviceconnection_detail_view,
             name="deviceconnection_detail",
         ),
+        path(
+            "api/v1/controller/batch-command/",
+            api_views.batch_command_list_view,
+            name="batch_command_list",
+        ),
+        path(
+            "api/v1/controller/batch-command/<uuid:pk>/",
+            api_views.batch_command_detail_view,
+            name="batch_command_detail",
+        ),
+        path(
+            "api/v1/controller/batch-command/execute/",
+            api_views.batch_command_execute_view,
+            name="batch_command_execute",
+        ),
     ]
 
 

openwisp_controller/connection/api/views.py

@@ -1,12 +1,18 @@
+from django.core.exceptions import ValidationError
+from django.db.models import Count
 from django.utils.translation import gettext_lazy as _
 from drf_yasg import openapi
 from drf_yasg.utils import swagger_auto_schema
+from rest_framework import status
 from rest_framework.generics import (
+    GenericAPIView,
+    ListAPIView,
     ListCreateAPIView,
     RetrieveAPIView,
     RetrieveUpdateDestroyAPIView,
     get_object_or_404,
 )
+from rest_framework.response import Response
 from swapper import load_model
 
 from openwisp_utils.api.pagination import OpenWispPagination
@@ -17,6 +23,9 @@
     RelatedDeviceProtectedAPIMixin,
 )
 from .serializers import (
+    BatchCommandDetailSerializer,
+    BatchCommandExecuteSerializer,
+    BatchCommandSerializer,
     CommandSerializer,
     CredentialSerializer,
     DeviceConnectionSerializer,
@@ -26,6 +35,7 @@
 Device = load_model("config", "Device")
 Credentials = load_model("connection", "Credentials")
 DeviceConnection = load_model("connection", "DeviceConnection")
+BatchCommand = load_model("connection", "BatchCommand")
 
 
 class BaseCommandView(RelatedDeviceProtectedAPIMixin):
@@ -138,6 +148,55 @@ class DeviceConnectionListCreateView(BaseDeviceConnection, ListCreateAPIView):
 DeviceConnenctionListCreateView = DeviceConnectionListCreateView
 
 
+class BatchCommandExecuteView(ProtectedAPIMixin, GenericAPIView):
+    model = BatchCommand
+    queryset = BatchCommand.objects.all()
+    serializer_class = BatchCommandExecuteSerializer
+
+    def post(self, request):
+        serializer = self.get_serializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        serializer.validated_data.pop("execute_all", None)
+        try:
+            batch = BatchCommand.execute(**serializer.validated_data)
+        except ValidationError as e:
+            return Response(
+                getattr(e, "message_dict", e.messages),
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        return Response({"batch": str(batch.pk)}, status=201)
+
+    def get(self, request):
+        serializer = self.get_serializer(
+            data=request.query_params,
+            dry_run=True,
+        )
+        serializer.is_valid(raise_exception=True)
+        serializer.validated_data.pop("execute_all", None)
+        try:
+            data = BatchCommand.dry_run(**serializer.validated_data)
+        except ValidationError as e:
+            return Response(
+                getattr(e, "message_dict", e.messages),
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        data["devices"] = [str(d.pk) for d in data["devices"]]
+        return Response(data)
+
+
+class BatchCommandListView(ProtectedAPIMixin, ListAPIView):
+    queryset = BatchCommand.objects.annotate(device_count=Count("devices")).order_by(
+        "-created"
+    )
+    serializer_class = BatchCommandSerializer
+    pagination_class = OpenWispPagination
+
+
+class BatchCommandDetailView(ProtectedAPIMixin, RetrieveAPIView):
+    queryset = BatchCommand.objects.annotate(device_count=Count("devices"))
+    serializer_class = BatchCommandDetailSerializer
+
+
 class DeviceConnectionDetailView(BaseDeviceConnection, RetrieveUpdateDestroyAPIView):
     def get_object(self):
         queryset = self.filter_queryset(self.get_queryset())
@@ -149,6 +208,9 @@ def get_object(self):
         return obj
 
 
+batch_command_execute_view = BatchCommandExecuteView.as_view()
+batch_command_list_view = BatchCommandListView.as_view()
+batch_command_detail_view = BatchCommandDetailView.as_view()
 command_list_create_view = CommandListCreateView.as_view()
 command_details_view = CommandDetailsView.as_view()
 credential_list_create_view = CredentialListCreateView.as_view()