Initial draft of queue inspect and delete APIs

Author: korylprince

api/types.go

@@ -85,3 +85,12 @@ func (r *APIResult) Error() error {
 
 	return nil
 }
+
+// QueueAPIResult is the result of queue APIs.
+type QueueAPIResult struct {
+	// Status is the per-enrollment ID results of queue APIs.
+	// Map key is the enrollment ID.
+	Status map[string]*Error `json:"status,omitempty"`
+	// Error is present if there was a general error with the queue API call.
+	Error *Error `json:"error,omitempty"`
+}

docs/openapi.yaml

@@ -102,6 +102,59 @@ paths:
           schema:
             type: string
             example: '1'
+  /v1/queue/{id}:
+    get:
+      description: Retrieve queued MDM commands for a specific enrollment ID with pagination support
+      security:
+        - basicAuth: []
+      parameters:
+        - name: id
+          in: path
+          description: Enrollment ID of device- or user-channel enrollment. Typically a UUID-looking identifier.
+          required: true
+          schema:
+            type: string
+            example: '299BD49-1A0C-422C-B285-2E4FF087C673'
+        - name: cursor
+          in: query
+          description: Pagination cursor for retrieving the next page of results. Omit or leave empty to start from the beginning.
+          required: false
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: Maximum number of commands to retrieve per page.
+          required: false
+          schema:
+            type: integer
+            example: 100
+      responses:
+        '200':
+          description: Successfully retrieved queued commands
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/QueuedCommandsResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '500':
+          description: Error retrieving queued commands
+  /v1/queue/{id*}:
+    delete:
+      description: Clear all queued MDM commands for one or more enrollment IDs
+      security:
+        - basicAuth: []
+      parameters:
+        - $ref: '#/components/parameters/idParam'
+      responses:
+        '204':
+          description: Successfully cleared queued commands for all enrollment IDs
+        '207':
+          $ref: '#/components/responses/QueueAPIResultSomeFailed'
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '500':
+          $ref: '#/components/responses/QueueAPIResultAllFailed'
   /v1/escrowkeyunlock:
     post:
       description: "Perform an Escrow Key Unlock against Apple's API. Uses the APNs certificate of the provided topic for mTLS authentication. Note that despite all parameters being in the HTTP body (form) this endpoint moves the appropriate parameters to the URL query parameters per Apple's documentation. The response body, status, and headers are handed straight through from the Apple endpoint."
@@ -228,6 +281,18 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/APIResult'
+    QueueAPIResultSomeFailed:
+      description: Some requests succeeded and some failed. Returns JSON queue API response object including errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/QueueAPIResult'
+    QueueAPIResultAllFailed:
+      description: All requests failed. Returns JSON queue API response object including errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/QueueAPIResult'
   schemas:
     APIResult:
       type: object
@@ -276,3 +341,44 @@ components:
           format: date-time
           description: Expiration date of the uploaded APNs certificate.
           example: '2026-01-07T04:04:46Z'
+    QueuedCommandsResponse:
+      type: object
+      properties:
+        commands:
+          type: array
+          description: Array of queued MDM commands
+          items:
+            type: object
+            properties:
+              command_uuid:
+                type: string
+                format: uuid
+                example: 'fedd659e-fc3c-4e35-8bb1-c8f51ae542a5'
+              request_type:
+                type: string
+                example: 'ProfileList'
+              command:
+                type: string
+                format: byte
+                description: The full MDM command plist data, base64-encoded.
+                example: |-
+                  PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPCFET0NUWVBFIHBsaXN0IFBVQkxJQyAiLS8vQXBwbGUvL0RURCBQTElTVCAxLjAvL0VOIiAiaHR0cDovL3d3dy5hcHBsZS5jb20vRFREcy9Qcm9wZXJ0eUxpc3QtMS4wLmR0ZCI+CjxwbGlzdCB2ZXJzaW9uPSIxLjAiPgo8ZGljdD4KPGtleT5Db21tYW5kPC9rZXk+CjxkaWN0PgogICAgPGtleT5SZXF1ZXN0VHlwZTwva2V5PgogICAgPHN0cmluZz5Qcm9maWxlTGlzdDwvc3RyaW5nPgo8L2RpY3Q+CjxrZXk+Q29tbWFuZFVVSUQ8L2tleT4KPHN0cmluZz5mZWRkNjU5ZS1mYzNjLTRlMzUtOGJiMS1jOGY1MWFlNTQyYTU8L3N0cmluZz4KPC9kaWN0Pgo8L3BsaXN0Pg==
+        next_cursor:
+          type: string
+          description: Cursor for retrieving the next page of results. Empty if no more results available.
+    QueueAPIResult:
+      type: object
+      description: Result of queue API operations
+      properties:
+        status:
+          type: object
+          description: Per-enrollment ID error status. Map key is the enrollment ID.
+          properties:
+            $id:
+              type: string
+              description: Error message for this enrollment ID
+          example:
+            '299BD49-1A0C-422C-B285-2E4FF087C673': 'queue not found'
+            'E2E4A8EB-45EE-488D-B9D7-4CC3B1C40699': 'database error'
+        error:
+          type: string

storage/queue.go

@@ -17,3 +17,14 @@ type CommandAndReportResultsStore interface {
 type CommandEnqueuer interface {
 	EnqueueCommand(ctx context.Context, id []string, cmd *mdm.Command) (map[string]error, error)
 }
+
+// CommandQueueAPIStore can retrieve and clear queued commands by enrollment ID.
+type CommandQueueAPIStore interface {
+	// RetrieveQueuedCommands retrieves queued commands for the given enrollment ID.
+	// The cursor is used for pagination; an empty cursor retrieves from the start.
+	// Limit specifies the maximum number of commands to retrieve. If limit is zero or negative, all commands are retrieved.
+	// The retrieved commands and the next cursor (if more commands are available) are returned, or an error if any.
+	RetrieveQueuedCommands(ctx context.Context, id, cursor string, limit int) (commands []*mdm.Command, nextCursor string, err error)
+	// ClearQueueByID clears all queued commands for the given enrollment ID.
+	ClearQueueByID(ctx context.Context, id string) error
+}