Support ad-hoc CWL workflows

CHANGES.rst

@@ -12,6 +12,13 @@ Changes
 
 Changes:
 --------
+- Add support for ad-hoc `CWL` workflow execution through the ``POST /jobs`` endpoint using ``multipart/mixed``
+  or ``multipart/related`` content types. Users can now deploy and execute a `Process` in a single request by
+  submitting both the `CWL` workflow definition (with ``Content-Profile: http://www.opengis.net/def/ogcapi-processes/2.0/process-description``)
+  and execution parameters (with ``Content-Profile: http://www.opengis.net/def/ogcapi-processes/2.0/execute``)
+  in a multipart request body. The workflow is automatically deployed (with temporary ``ad-hoc`` tagging) before
+  execution, eliminating the need for separate deployment and execution steps for one-time workflow runs
+  (resolves `#834 <https://github.com/crim-ca/weaver/issues/834>`_).
 - Adjust the `CLI` to return the ``OperationResult.message`` when the response body is empty (``HTTP 204 No Content``)
   to provide a clearer message to the user of what happened and indicate the state of the operation.
   Previously, the ``None`` content would be reported as is making it ambiguous about what occurred or whether it failed.

docs/source/package.rst

@@ -681,6 +681,123 @@ Example multipart request structure:
     - :ref:`proc_ogc_api_multi_cwl` for deployment request examples
     - |ogc-api-proc-part2|_ CWL Multipart Content conformance class
 
+.. _app_pkg_adhoc:
+
+Ad-hoc Workflow Execution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Weaver` supports *ad-hoc* workflow execution, allowing users to deploy and execute a :term:`CWL` workflow in a single
+request to the ``POST /jobs`` endpoint using ``multipart/mixed`` or ``multipart/related`` content types. This
+eliminates the need for separate :ref:`deployment <proc_op_deploy>` and :ref:`execution <proc_op_execute>` steps
+when running one-time workflows or testing workflow definitions.
+
+The multipart request must contain:
+
+1. One or more :term:`CWL` parts (workflow and any dependent tools) with
+   ``Content-Profile: http://www.opengis.net/def/ogcapi-processes/2.0/process-description``
+2. One execution request part with ``Content-Profile: http://www.opengis.net/def/ogcapi-processes/2.0/execute``
+   containing the job inputs and execution parameters
+
+When an ad-hoc execution request is received:
+
+- The workflow (and any dependent tools) are automatically deployed with ``ad-hoc`` tagging
+- The job is immediately submitted for execution using the provided inputs
+- The workflow remains deployed after execution and can be reused or cleaned up later
+
+Example Ad-hoc Execution Request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: http
+
+    POST /jobs HTTP/1.1
+    Host: weaver.example.com
+    Content-Type: multipart/mixed; boundary="adhoc-boundary"
+
+    --adhoc-boundary
+    Content-Type: application/cwl+json
+    Content-Profile: http://www.opengis.net/def/ogcapi-processes/2.0/process-description
+
+    {
+      "cwlVersion": "v1.2",
+      "class": "CommandLineTool",
+      "id": "adhoc-echo-tool",
+      "baseCommand": ["echo"],
+      "inputs": {
+        "message": "string"
+      },
+      "outputs": {
+        "output": {
+          "type": "stdout"
+        }
+      },
+      "requirements": {
+        "DockerRequirement": {
+          "dockerPull": "alpine:latest"
+        }
+      },
+      "stdout": "output.txt"
+    }
+
+    --adhoc-boundary
+    Content-Type: application/cwl+json
+    Content-Profile: http://www.opengis.net/def/ogcapi-processes/2.0/process-description
+
+    {
+      "cwlVersion": "v1.2",
+      "class": "Workflow",
+      "id": "adhoc-workflow",
+      "inputs": {
+        "message": "string"
+      },
+      "outputs": {
+        "result": {
+          "type": "File",
+          "outputSource": "echo_step/output"
+        }
+      },
+      "steps": {
+        "echo_step": {
+          "run": "adhoc-echo-tool",
+          "in": {
+            "message": "message"
+          },
+          "out": ["output"]
+        }
+      }
+    }
+
+    --adhoc-boundary
+    Content-Type: application/json
+    Content-Profile: http://www.opengis.net/def/ogcapi-processes/2.0/execute
+
+    {
+      "inputs": {
+        "message": "Hello from ad-hoc workflow!"
+      },
+      "outputs": {
+        "result": {
+          "transmissionMode": "reference"
+        }
+      },
+      "mode": "async",
+      "response": "document"
+    }
+
+    --adhoc-boundary--
+
+The response will be a standard :term:`Job` status document (see :ref:`proc_op_execute`) with the ``jobID``,
+``processID`` (the deployed workflow ID), and execution status. The job can be monitored and results retrieved
+using the standard :term:`Job` endpoints.
+
+.. note::
+    The deployed workflow and tools remain available after ad-hoc execution and are tagged with ``ad-hoc`` for
+    identification. They can be cleaned up using the :ref:`Undeploy <proc_op_undeploy>` operation if no longer needed.
+
+.. seealso::
+    - :ref:`proc_op_execute` for execution request details
+    - :ref:`app_pkg_multipart` for multipart :term:`CWL` packaging
+    - `crim-ca/weaver#834 <https://github.com/crim-ca/weaver/issues/834>`_ for implementation details
+
 .. _app_pkg_workflow:
 
 CWL Workflow