Merge pull request #101 from games-on-whales/dev-backend-api

Exposing Wolf events via API

.github/workflows/docker-build.yml

@@ -130,3 +130,43 @@ jobs:
             IMAGE_SOURCE=${{ steps.prep.outputs.github_server_url }}/${{ github.repository }}
           cache-from: ${{ steps.prep.outputs.cache_from }}
           cache-to: ${{ steps.prep.outputs.cache_to }}
+
+  test_devcontainer:
+    runs-on: ubuntu-latest
+    needs: buildx
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Login to GitHub Container Registry
+        if: steps.prep.outputs.has_github_token != '' # secrets not available in PRs
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GHCR_TOKEN }}
+
+      - name: Run tests in devcontainer
+        uses: devcontainers/[email protected]
+        with:
+          imageTag: devcontainer
+          imageName: ghcr.io/${{ github.repository_owner }}/wolf
+          cacheFrom: ghcr.io/${{ github.repository_owner }}/wolf:${{github.ref_name}}
+          push: never
+          # TODO:
+          # runCmd: |
+          #   cmake -Bbuild \
+          #         -H$GITHUB_WORKSPACE \
+          #         -DCMAKE_BUILD_TYPE=Debug \
+          #         -DCMAKE_CXX_EXTENSIONS=OFF \
+          #         -DTEST_VIRTUAL_INPUT=OFF \
+          #         -DTEST_DOCKER=ON \
+          #         -DTEST_RUST_WAYLAND=ON \
+          #         -DTEST_NVIDIA=OFF \
+          #         -DTEST_EXCEPTIONS=OFF \
+          #         -DTEST_UHID=OFF \
+          #         -G Ninja
+          #
+          #   ninja -j $(nproc) wolftests
+          #
+          #   ./wolftests --reporter JUnit::out=${{runner.workspace}}/report.xml --reporter console::out=-::colour-mode=ansi

.github/workflows/linux-build-test.yml

@@ -64,7 +64,6 @@ jobs:
                 -H$GITHUB_WORKSPACE \
                 -DCMAKE_BUILD_TYPE=Debug \
                 -DCMAKE_CXX_EXTENSIONS=OFF \
-                -DCMAKE_CXX_STANDARD=17 \
                 -DTEST_VIRTUAL_INPUT=OFF \
                 -DTEST_DOCKER=ON \
                 -DTEST_RUST_WAYLAND=ON \
@@ -96,7 +95,7 @@ jobs:
 
   # First build the common dependencies: Rust-based libgstwaylanddisplay
   build-gst-wayland:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - name: Prepare environment
         # ubuntu-latest breaks without libunwind-dev,
@@ -130,28 +129,22 @@ jobs:
           if-no-files-found: error
 
   test:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     needs: build-gst-wayland
     strategy:
       fail-fast: false
       matrix:
         cxx:
-          - g++-10
           - g++-12
-          - clang++-11
-          - clang++-14
+          - clang++-16
         build_type: [ Release ]
         shared: [ true, false ]
-        std: [ 17 ]
+        std: [ 20 ]
         include:
-          - cxx: g++-10
-            other_pkgs: [ g++-10 ]
           - cxx: g++-12
             other_pkgs: [ g++-12 ]
-          - cxx: clang++-11
-            other_pkgs: [ clang-11 ]
-          - cxx: clang++-14
-            other_pkgs: [ clang-14 ]
+          - cxx: clang++-16
+            other_pkgs: [ clang-16 ]
 
 
     steps:

CMakeLists.txt

@@ -11,7 +11,7 @@ if (CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
 
     # Optionally set things like CMAKE_CXX_STANDARD, CMAKE_POSITION_INDEPENDENT_CODE here
 
-    set(CMAKE_CXX_STANDARD 17)
+    set(CMAKE_CXX_STANDARD 20)
 
     set(CMAKE_CXX_STANDARD_REQUIRED ON)
 

docker/gstreamer.Dockerfile

@@ -86,6 +86,13 @@ RUN <<_GSTREAMER_INSTALL
     equivs-build $SOURCE_PATH/gstreamer.control
     dpkg -i gstreamer-wolf_${GSTREAMER_VERSION}_all.deb
 
+    # Add GstInterpipe
+    git clone https://github.com/RidgeRun/gst-interpipe.git $SOURCE_PATH/gst-interpipe
+    cd $SOURCE_PATH/gst-interpipe
+    mkdir build
+    meson build -Denable-gtk-doc=false
+    meson install -C build
+
     # Final cleanup stage
     apt-mark auto $DEV_PACKAGES
     apt-get autoremove -y --purge

docs/modules/ROOT/nav.adoc

@@ -11,6 +11,7 @@
 * Developer guide
 ** xref:dev:how-it-works.adoc[]
 ** xref:dev:manual_build.adoc[]
+** xref:dev:api.adoc[]
 ** xref:dev:code-structure.adoc[]
 ** xref:dev:gstreamer.adoc[]
 ** xref:dev:wayland.adoc[]

docs/modules/dev/pages/api.adoc

@@ -0,0 +1,70 @@
+:includedir: partial$
+= Wolf API
+
+Wolf exposes a REST API that allows you to interact with the platform programmatically. +
+The API can be accessed only via UNIX sockets, you can control the exact path by setting the `WOLF_SOCKET_PATH` environment variable. If you want to access the socket from outside the container, you should mount the socket to the host machine, ex: `-e WOLF_SOCKET_PATH=/var/run/wolf/wolf.sock` and `-v /var/run/wolf:/var/run/wolf` will allow you to access the socket from the host machine at `/var/run/wolf/wolf.sock`.
+
+You can test out the API using the `curl` command, for example, to get the OpenAPI specification you can run:
+
+[source,bash]
+....
+curl --unix-socket /var/run/wolf/wolf.sock http://localhost/api/v1/openapi-schema
+....
+
+When looking at the examples in the xref:api_reference[] remember to add the `--unix-socket` flag to the `curl` command.
+
+== Exposing the API via TCP
+
+[WARNING]
+====
+Exposing the API is highly dangerous, via the API you can pair clients to the server, execute arbitrary commands, and more. +
+*Make sure to secure the API properly if you decide to expose it.*
+====
+
+If you want to expose the API via TCP you can use a reverse proxy like `nginx`, for example, to expose the API on port 8080 you can use the following config
+
+....
+server {
+    listen 8080;
+
+    location / {
+        proxy_pass http://unix:/var/run/wolf/wolf.sock;
+        proxy_http_version 1.0;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+....
+
+Save it as `wolf.conf` and start an Nginx container with the following command:
+
+[source,bash]
+....
+docker run --name wolf-proxy \
+           --network=host \
+           -v /var/run/wolf/wolf.sock:/var/run/wolf/wolf.sock:rw \
+           -v ./wolf.conf:/etc/nginx/conf.d/wolf.conf:ro \
+           nginx
+....
+
+You can now access the API via `http://localhost:8080`, ex:
+
+[source,bash]
+....
+curl localhost:8080/api/v1/openapi-schema
+....
+
+[#api_reference]
+== API Reference
+
+[subs=macros]
+++++
+<script
+  id="api-reference"
+  type="application/json">
+include::{includedir}/spec.json[]
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+++++