Added REST web server to interface with capiocl::Engine

.github/workflows/ci-test.yml

@@ -43,7 +43,8 @@ jobs:
           apt-get update
           apt-get install -y git              \
             cmake make ninja-build  sudo      \
-            python3 python3-pip python3-venv 
+            python3 python3-pip python3-venv  \
+            libcurl4-gnutls-dev
 
       - name: "Run CMake"
         shell: bash
@@ -76,7 +77,7 @@ jobs:
           sudo apt-get install -y git              \
                cmake make ninja-build  sudo      \
                python3 python3-pip python3-venv  \
-               gcc g++
+               gcc g++ libcurl4-gnutls-dev
 
       - name: "Compile tests"
         run: |

.github/workflows/python-bindings.yml

@@ -33,15 +33,15 @@ jobs:
       # Install platform build dependencies
       - name: "Install system packages (Ubuntu)"
         if: startsWith(matrix.on, 'ubuntu-')
-        run: sudo apt-get update && sudo apt-get install -y ninja-build g++ cmake
+        run: sudo apt-get update && sudo apt-get install -y ninja-build g++ cmake libcurl4-gnutls-dev
 
       - name: "Setup Homebrew (macOS)"
         if: startsWith(matrix.on, 'macos-')
         uses: Homebrew/actions/setup-homebrew@main
 
       - name: "Install system packages (macOS)"
         if: startsWith(matrix.on, 'macos-')
-        run: brew install ninja gcc cmake
+        run: brew install ninja gcc cmake curl
 
       - name: "Create virtual environment"
         run: |

CMakeLists.txt

@@ -57,11 +57,19 @@ FetchContent_Declare(
         GIT_TAG v1.4.3
 )
 
+FetchContent_Declare(
+        httplib
+        GIT_REPOSITORY https://github.com/yhirose/cpp-httplib.git
+        GIT_TAG v0.29.0
+)
+
+
 set(JSONCONS_BUILD_TESTS OFF CACHE BOOL "" FORCE)
 set(JSONCONS_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
 set(JSONCONS_BUILD_FUZZERS OFF CACHE BOOL "" FORCE)
+set(HTTPLIB_USE_ZSTD_IF_AVAILABLE OFF CACHE BOOL "" FORCE)
 
-FetchContent_MakeAvailable(jsoncons tomlplusplus)
+FetchContent_MakeAvailable(jsoncons tomlplusplus httplib)
 
 if (BUILD_PYTHON_BINDINGS)
     FetchContent_Declare(
@@ -135,10 +143,19 @@ target_include_directories(libcapio_cl PUBLIC
         ${jsoncons_SOURCE_DIR}/include
         ${CAPIOCL_JSON_SCHEMAS_DIRECTORY}
         ${TOMLPLUSPLUS_SOURCE_DIR}/include
+        ${httplib_SOURCE_DIR}
 )
 
 target_link_libraries(libcapio_cl PUBLIC)
-target_link_libraries(libcapio_cl PRIVATE tomlplusplus::tomlplusplus)
+target_link_libraries(libcapio_cl PRIVATE
+        tomlplusplus::tomlplusplus
+        httplib::httplib
+)
+
+find_library(LIBANL anl)
+if(LIBANL)
+    target_link_libraries(libcapio_cl PRIVATE ${LIBANL})
+endif ()
 
 #####################################
 # Install rules
@@ -173,6 +190,9 @@ endif ()
 # Tests (only when built standalone)
 #####################################
 if (CAPIO_CL_BUILD_TESTS)
+
+    find_package(CURL REQUIRED)
+
     message(STATUS "Building CAPIO-CL tests")
 
     FetchContent_Declare(
@@ -189,8 +209,13 @@ if (CAPIO_CL_BUILD_TESTS)
     target_link_libraries(CAPIO_CL_tests PRIVATE
             libcapio_cl
             GTest::gtest_main
+            CURL::libcurl
     )
 
+    if(LIBANL)
+        target_link_libraries(CAPIO_CL_tests PRIVATE ${LIBANL})
+    endif ()
+
     target_include_directories(CAPIO_CL_tests PRIVATE
             ${CMAKE_CURRENT_SOURCE_DIR}
             ${CMAKE_CURRENT_SOURCE_DIR}/src

README.md

@@ -10,28 +10,25 @@
 ![C++](https://img.shields.io/badge/C%2B%2B-%E2%89%A517-blueviolet?logo=c%2B%2B&logoColor=white)
 ![Python Bindings](https://img.shields.io/badge/Python_Bindings-3.10–3.14-darkgreen?style=flat&logo=python&logoColor=white&labelColor=gray)
 
-
 #### Platform support
 
-| OS / Arch | ![x86_64](https://img.shields.io/badge/x86__64-121212?logo=intel&logoColor=blue) | ![ARM](https://img.shields.io/badge/ARM-121212?logo=arm&logoColor=0091BD) | ![RISC-V](https://img.shields.io/badge/RISC--V-121212?logo=riscv&logoColor=F9A825) |
-|-----------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------|------------------------------------------------------------------------------------|
+| OS / Arch                                                                          | ![x86_64](https://img.shields.io/badge/x86__64-121212?logo=intel&logoColor=blue) | ![ARM](https://img.shields.io/badge/ARM-121212?logo=arm&logoColor=0091BD) | ![RISC-V](https://img.shields.io/badge/RISC--V-121212?logo=riscv&logoColor=F9A825) |
+|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------|------------------------------------------------------------------------------------|
 | ![Ubuntu](https://img.shields.io/badge/Ubuntu-121212?logo=ubuntu&logoColor=E95420) | YES                                                                              | YES                                                                       | YES                                                                                |
 | ![macOS](https://img.shields.io/badge/macOS-121212?logo=apple&logoColor=white)     | YES                                                                              | YES                                                                       | N.A.                                                                               |
 
-
 #### Documentation
 
 - [![Core Language](https://img.shields.io/badge/Core%20Language-10.1007%2Fs10766--025--00789--0-%23cc5500?logo=doi&logoColor=white&labelColor=2b2b2b)](https://doi.org/10.1007/s10766-025-00789-0)
 - [![Metadata Streaming](https://img.shields.io/badge/Metadata%20Streaming-10.1145%2F3731599.3767577-%23cc5500?logo=doi&logoColor=white&labelColor=2b2b2b)](https://doi.org/10.1145/3731599.3767577)
 - [![Doxygen documentation](https://img.shields.io/github/v/release/High-Performance-IO/CAPIO-CL?label=Doxygen%20documentation&labelColor=2b2b2b&color=brown&logo=readthedocs&logoColor=white)](https://github.com/High-Performance-IO/CAPIO-CL/releases/latest/download/documentation.pdf)
 
-
 **CAPIO-CL** is a novel I/O coordination language that enables users to annotate file-based workflow data dependencies
 with **synchronization semantics** for files and directories.
 Designed to facilitate **transparent overlap between computation and I/O operations**, CAPIO-CL allows multiple
 producer–consumer application modules to coordinate efficiently using a **JSON-based syntax**.
 
-For detailed documentation and examples, please visit: 
+For detailed documentation and examples, please visit:
 
 [![CAPIO Website](https://img.shields.io/badge/CAPIO%20Website-Documentation-brightgreen?logo=readthedocs&logoColor=white)](https://capio.hpc4ai.it/docs/coord-language/)
 
@@ -184,7 +181,49 @@ engine.print()
 Serializer.dump(engine, "my_workflow", "my_workflow.json")
 ```
 
-# Team
+## CapioCL Web API Documentation
+
+This section describes the REST-style Web API exposed by the CapioCL Web Server.
+The server provides HTTP endpoints for configuring and querying the CapioCL engine at runtime. 
+Within the `bruno_webapi_tests` you can find several tests and examples on how to perform
+requests to the API webserver using [bruno](https://www.usebruno.com).
+
+All endpoints communicate using JSON over HTTP. To enable the webserver, users needs to explicitly start it with:
+
+```cpp
+capiocl::engine::Engine engine();
+
+// start engine with default parameters
+engine.startApiServer();
+
+// or by specifying the address and port:
+engine.startApiServer("127.0.0.1", 5520);
+```
+
+
+or equivalently in python with:
+
+```python
+engine = py_capio_cl.Engine()
+
+#start engine with default parameters
+engine.startApiServer()
+
+# or by specifying the address and port:
+engine.startApiServer("127.0.0.1", 5520)
+```
+
+By default, the webserver listens only on local connection at the following address: ```127.0.0.1:5520```. No
+authentication
+services are currently available, and as such, users should put particular care when allowing connections from external
+endpoints.
+
+## Notes
+
+- All GET endpoints expect a JSON body containing the targeted file path.
+- The API is intended for local control and orchestration, not public exposure.
+
+---
 
 ## Developing team
 

bindings/python_bindings.cpp

@@ -98,6 +98,8 @@ PYBIND11_MODULE(_py_capio_cl, m) {
         .def("isCommitted", &capiocl::engine::Engine::isCommitted, py::arg("path"))
         .def("setHomeNode", &capiocl::engine::Engine::setHomeNode, py::arg("path"))
         .def("getPaths", &capiocl::engine::Engine::getPaths)
+        .def("startApiServer", &capiocl::engine::Engine::startApiServer,
+             py::arg("address") = "127.0.0.1", py::arg("port") = 5520)
         .def("__str__", &capiocl::engine::Engine::print)
         .def("__repr__",
              [](const capiocl::engine::Engine &e) {

bruno_webapi_tests/add_consumer.bru

@@ -0,0 +1,23 @@
+meta {
+  name: add_consumer
+  type: http
+  seq: 2
+}
+
+post {
+  url: http://localhost:5520/consumer
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "path" : "/tmp/test.txt",
+    "consumer" : "sample2"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}

bruno_webapi_tests/add_file_dependency.bru

@@ -0,0 +1,23 @@
+meta {
+  name: add_file_dependency
+  type: http
+  seq: 4
+}
+
+post {
+  url: http://localhost:5520/dependency
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "path" : "/tmp/test.txt",
+    "dependency" : "myFile.dat"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}

bruno_webapi_tests/add_producer.bru

@@ -0,0 +1,23 @@
+meta {
+  name: add_producer
+  type: http
+  seq: 3
+}
+
+post {
+  url: http://localhost:5520/producer
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "path" : "/tmp/test.txt",
+    "producer" : "sample1"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}

bruno_webapi_tests/add_workflow_name.bru

@@ -0,0 +1,22 @@
+meta {
+  name: add_workflow_name
+  type: http
+  seq: 1
+}
+
+post {
+  url: http://localhost:5520/workflow
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "name": "workflow_demo"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}

bruno_webapi_tests/bruno.json

@@ -0,0 +1,9 @@
+{
+  "version": "1",
+  "name": "bruno_webapi_tests",
+  "type": "collection",
+  "ignore": [
+    "node_modules",
+    ".git"
+  ]
+}

bruno_webapi_tests/get_commit_close_count.bru

@@ -0,0 +1,22 @@
+meta {
+  name: get_commit_close_count
+  type: http
+  seq: 18
+}
+
+get {
+  url: http://localhost:5520/commit/close-count
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "path" : "/tmp/test.txt"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}

bruno_webapi_tests/get_commit_on_n_files_count.bru

@@ -0,0 +1,22 @@
+meta {
+  name: get_commit_on_n_files_count
+  type: http
+  seq: 17
+}
+
+get {
+  url: http://localhost:5520/commit/file-count
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "path" : "/tmp/test.txt"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}

bruno_webapi_tests/get_commit_rule.bru

@@ -0,0 +1,22 @@
+meta {
+  name: get_commit_rule
+  type: http
+  seq: 16
+}
+
+get {
+  url: http://localhost:5520/commit
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "path" : "/tmp/test.txt"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}

bruno_webapi_tests/get_consumer.bru

@@ -0,0 +1,22 @@
+meta {
+  name: get_consumer
+  type: http
+  seq: 14
+}
+
+get {
+  url: http://localhost:5520/consumer
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "path" : "/tmp/test.txt"
+  }
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}