web-server: Fix usage of Civetweb server

Co-authored-by: Daniel Myhrman <danielmy@axis.com>
Co-authored-by: Fernando Esquirio Torres <fernando.torres@axis.com>
Co-authored-by: Mattias Axelsson <mattiaax@axis.com>

Author: 4 people

.github/custom-linters/lint-example-structure.sh

@@ -1,38 +1,78 @@
 #!/bin/bash
 
-. "$(git rev-parse --show-toplevel)"/.github/utils/util-functions.sh
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+. "$REPO_ROOT"/.github/utils/util-functions.sh
+cd "$REPO_ROOT" || exit 1
 
 #-------------------------------------------------------------------------------
 # Functions
 #-------------------------------------------------------------------------------
 
+workflow_exists() {
+  local example_name="$1"
+  [ -f ".github/workflows/${example_name}.yml" ]
+}
+
+collect_examples_for_lint() {
+  local collected=()
+
+  for dir in *; do
+    [ -d "$dir" ] || continue
+
+    # If the top-level directory has a workflow, it is an example on its own.
+    if workflow_exists "$dir"; then
+      collected+=("$dir")
+      continue
+    fi
+
+    # Otherwise treat it as a container folder and collect child examples.
+    local found_child_examples=no
+    for child in "$dir"/*; do
+      [ -d "$child" ] || continue
+      [ -f "$child/Dockerfile" ] || continue
+      found_child_examples=yes
+      collected+=("$(basename "$child")")
+    done
+
+    # If neither a workflow nor child examples are found, keep it as-is so
+    # the lint can report that the directory lacks a workflow.
+    [ "$found_child_examples" = yes ] || collected+=("$dir")
+  done
+
+  if [ "${#collected[@]}" -gt 0 ]; then
+    printf '%s\n' "${collected[@]}" | sort -u
+  fi
+}
+
 check_examples_have_workflow_file() {
   local ret=0
   local fail_list=()
   local yml_array=
-  local acap_array=
+  local example_array=
 
   print_section "Verify that all examples have a workflow .yml file"
 
   # shellcheck disable=SC2207
   yml_array=($(ls .github/workflows))
-  # shellcheck disable=SC2207,SC2035
-  acap_array=($(ls -d */))
+  example_array=()
+  while IFS= read -r example; do
+    [ -n "$example" ] && example_array+=("$example")
+  done < <(collect_examples_for_lint)
 
-  for acap in "${acap_array[@]%?}"; do
+  for example in "${example_array[@]}"; do
     local found_workflow_file=no
     for yml in "${yml_array[@]}"; do
-      [ "$acap.yml" = "$yml" ] && {
+      [ "$example.yml" = "$yml" ] && {
         found_workflow_file=yes
         break
       }
     done
-    [ "$found_workflow_file" = yes ] || fail_list+=("$acap")
+    [ "$found_workflow_file" = yes ] || fail_list+=("$example")
   done
 
   if [ "${#fail_list[@]}" -ne 0 ]; then
-    print_line "Application directories"
-    print_list_no_split "${acap_array[@]%?}"
+    print_line "Example directories"
+    print_list_no_split "${example_array[@]}"
     print_line "YML files"
     print_list_no_split "${yml_array[@]}"
     print_line "ERROR: Applications that dont't have .yml file under .github/workflows:"
@@ -47,16 +87,13 @@ check_examples_have_workflow_file() {
 
 check_examples_have_top_readme_entry() {
   local ret=0
-  local acap_list=
+  local example_list=
   local readme_examples=
   local unique=
 
   print_section "Verify that all examples have an entry in top-README"
 
-  # Find directories that do not start with dot
-  acap_list="$(find . -maxdepth 1 -type d | sed 's|^\./||' |
-             grep -v '^[.]' |
-             sort)"
+  example_list="$(collect_examples_for_lint)"
 
   # Find lines starting with '* ['
   # The grep removes anything but '[*]', then remove entries with space
@@ -67,7 +104,7 @@ check_examples_have_top_readme_entry() {
                      grep -oe '[0-9a-z-]*')"
 
   print_line "# Control that all example directories have an entry in README"
-  unique=$(printf '%s\n%s' "${acap_list}" "${readme_examples}" | sort | uniq -u)
+  unique=$(printf '%s\n%s' "${example_list}" "${readme_examples}" | sort | uniq -u)
   if [ "$unique" ]; then
     print_line "ERROR: Mismatch between example directories and entries in README.md."
     print_line "       The following items are only found in one of the two:"

…b/workflows/web-server-using-fastcgi.yml …orkflows/http-requests-using-fastcgi.yml.github/workflows/web-server-using-fastcgi.yml renamed to .github/workflows/http-requests-using-fastcgi.yml .github/workflows/web-server-using-fastcgi.yml renamed to .github/workflows/http-requests-using-fastcgi.yml

@@ -1,11 +1,11 @@
-name: Build web-server-using-fastcgi application
+name: Build http-requests-using-fastcgi application
 on:
   workflow_dispatch:
   push:
     paths:
-      - 'web-server-using-fastcgi/**'
-      - '!web-server-using-fastcgi/README.md'
-      - '.github/workflows/web-server-using-fastcgi.yml'
+      - 'web-server/http-requests-using-fastcgi/**'
+      - '!web-server/http-requests-using-fastcgi/README.md'
+      - '.github/workflows/http-requests-using-fastcgi.yml'
 jobs:
   test-app:
     name: Test app
@@ -16,7 +16,7 @@ jobs:
         arch: ["armv7hf", "aarch64"]
     env:
       EXREPO: acap-native-examples
-      EXNAME: web-server-using-fastcgi
+      EXNAME: web-server/http-requests-using-fastcgi
     steps:
       - uses: actions/checkout@v6
       - uses: docker/setup-buildx-action@v4

.github/workflows/web-server.yml …flows/reverse-proxy-using-fixed-port.yml.github/workflows/web-server.yml renamed to .github/workflows/reverse-proxy-using-fixed-port.yml .github/workflows/web-server.yml renamed to .github/workflows/reverse-proxy-using-fixed-port.yml

@@ -1,11 +1,11 @@
-name: Build web-server application
+name: Build reverse-proxy-using-fixed-port application
 on:
   workflow_dispatch:
   push:
     paths:
-      - 'web-server/**'
-      - '!web-server/README.md'
-      - '.github/workflows/web-server.yml'
+      - 'web-server/reverse-proxy-using-fixed-port/**'
+      - '!web-server/reverse-proxy-using-fixed-port/README.md'
+      - '.github/workflows/reverse-proxy-using-fixed-port.yml'
 jobs:
   test-app:
     name: Test app
@@ -16,7 +16,7 @@ jobs:
         arch: ["armv7hf", "aarch64"]
     env:
       EXREPO: acap-native-examples
-      EXNAME: web-server
+      EXNAME: web-server/reverse-proxy-using-fixed-port
     steps:
       - uses: actions/checkout@v6
       - uses: docker/setup-buildx-action@v4

README.md

@@ -83,10 +83,12 @@ The examples are organized into logical groups to help you find the most relevan
 
 - [curl-openssl](./curl-openssl/)
   - An example that use cURL and OpenSSL libraries to retrieve a file securely from an external server.
-- [web-server](./web-server/)
-  - An example in C that serves HTTP requests by setting up the Axis device web server in a reverse proxy configuration and route to a custom web server running in the ACAP application.
-- [web-server-using-fastcgi](./web-server-using-fastcgi/)
-  - An example in C and explains how to build an ACAP application that can handle HTTP requests sent to the Axis device, using the device's own web server.
+
+- Web server examples:
+  - [reverse-proxy-using-fixed-port](./web-server/reverse-proxy-using-fixed-port/)
+    - An example in C that serves HTTP requests by setting up the Axis device web server in a reverse proxy configuration and routing to a custom web server running in the ACAP application.
+  - [http-requests-using-fastcgi](./web-server/http-requests-using-fastcgi/)
+    - An example in C and explains how to build an ACAP application that can handle HTTP requests sent to the Axis device, using the device's own web server.
 
 ### Event handling
 

web-server/README.md

@@ -1,194 +1,18 @@
 *Copyright (C) 2021, Axis Communications AB, Lund, Sweden. All Rights Reserved.*
 
-# Serve HTTP requests through reverse proxy
+# Web server examples introduction
 
-This example demonstrates how to setup the Axis device web server (Apache) in a
-[Reverse Proxy](https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html)
-configuration, where HTTP requests to the application are routed to a web server
-[CivetWeb](https://github.com/civetweb/civetweb) running inside the ACAP application
-and acting as a CGI.
+This folder contains ACAP Native SDK examples that show two ways to expose HTTP endpoints and web content on an Axis device.
 
-> [!NOTE]
-> The web server runs on the port specified in the application,
-> however there is a possibility that the port already is in use.
-> For more information on common ports used by Axis devices, see the
-> [commonly used network ports](https://help.axis.com/en-us/axis-os-knowledge-base#commonly-used-network-ports)
-> in the AXIS OS knowledge base. To change the port of the application,
-> both the [`web_server_rev_proxy.c`](./app/web_server_rev_proxy.c) and [`manifest.json`](./app/manifest.json] file have to be updated before
-> building the application.
+## Available examples
 
-The advantage of a webserver proxy is that when porting existing code to your
-ACAP application, its request handling can remain largely unmodified. This eases
-the task of sharing code between platforms. The webserver proxy method enforces
-a URL routing scheme as follows:
+1. **Reverse proxy using fixed port**
+ The reverse proxy example using CivetWeb demonstrates how to setup the Axis device web server (Apache) in a Reverse Proxy configuration, where HTTP requests to the application are routed to a web server CivetWeb running inside the ACAP application and acting as a CGI. See [reverse-proxy-using-fixed-port](./reverse-proxy-using-fixed-port/).
 
-`http://<AXIS_DEVICE_IP>/local/<appName>/<apiPath>`
+2. **HTTP requests using FastCGI**
+ The HTTP request example using FastCGI explains how to build an ACAP application that can handle HTTP requests sent to the Axis device. The application uses FastCGI to handle the request and response, and uriparser to parse the received query parameters. See [http-requests-using-fastcgi](./http-requests-using-fastcgi/).
 
-With `<appName>` and `<apiPath>` as defined in the manifest.
+## Which one to use
 
-Note that this example shows the reverse proxy concept using CivetWeb, but you are
-free to use any webserver of your choice.
-
-## Alternative approach
-
-Another example that serves HTTP requests is
-[web-server-using-fastcgi](../web-server-using-fastcgi), where the Axis device
-web server and the supported ACAP API
-[FastCGI](https://developer.axis.com/acap/api/native-sdk-api/#fastcgi)
-are used.
-
-## Reverse proxy configuration in Apache server
-
-A reverse proxy configuration provides a flexible way for an ACAP application
-to expose an external API through the Apache Server in AXIS OS and internally
-route the requests to a web server running in the ACAP application.
-
-The Apache server is configured using the `manifest.json` file in an ACAP
-application. In `manifest.json` under `configuration`, it is possible to specify
-a `settingPage` and a `reverseProxy` where the latter will connect the CivetWeb
-server to the Apache server.
-
-Prior to manifest 1.5.0, reverse proxy was only supported through the
-postinstall script. The manifest based method is more strict on URLs in order to
-avoid name clashes that could occur in the old mechanism. When upgrading, your
-URLs will change to the format shown in
-[Serve HTTP requests through reverse proxy](#serve-http-requests-through-reverse-proxy).
-
-The web server running in the ACAP application can also be exposed directly to
-the network by allowing external access to the port in the network
-configuration for the device. There are disadvantages with exposing Web
-Server directly to the network such as non standard ports and no reuse of
-authentication, TLS and other features that comes with Apache Server.
-
-## CivetWeb web server
-
-CivetWeb is an embeddable C web server for Linux. It is a great solution
-for running a web server on embedded Linux. Apart from being a
-HTTP server, it has a C API which can be extended as desired. The CivetWeb Web
-Server [documentation](https://github.com/civetweb/civetweb/) describes the
-configuration in detail. CivetWeb is open source, and will contain different
-licenses depending on the features you build it with. Please see
-[CivetWeb's repository](https://github.com/civetweb/civetweb/) for more information.
-
-## Getting started
-
-These instructions will guide you on how to execute the code. Below is the
-structure used in the example:
-
-```sh
-web-server
-├── app
-│   ├── LICENSE
-│   └── manifest.json
-├── Dockerfile
-└── README.md
-```
-
-- **app/LICENSE** - Lists open source licensed source code in the application.
-- **app/manifest.json** - Defines the application and its configuration.
-- **Dockerfile** - Builds an Axis container image and the specified example.
-- **README.md** - Step by step instructions on how to run the example.
-
-## Limitations
-
-- Apache Reverse Proxy can not translate content with absolute addresses (i.e.
-  /image.png) in the HTML page. Use only relative content (i.e. image.png or
-../image.png). See [how to handle relative URLs correctly with a reverse proxy](https://serverfault.com/questions/561892/how-to-handle-relative-urls-correctly-with-a-reverse-proxy)
-for more information.
-
-### How to run the code
-
-Below is the step by step instructions on how to execute the program. So
-basically starting with the generation of the .eap file to running it on a
-device.
-
-#### Build the application
-
-Standing in your working directory run the following commands:
-
-> [!NOTE]
->
-> Depending on the network your local build machine is connected to,
-you may need to add proxy
-> settings for Docker. See
-> [Proxy in build time](https://developer.axis.com/acap/develop/proxy/#proxy-in-build-time).
-
-```sh
-docker build --platform=linux/amd64 --tag <APP_IMAGE> --build-arg ARCH=<ARCH> .
-```
-
-- `<APP_IMAGE>` is the name to tag the image with, e.g., `web-server:1.0`
-- `<ARCH>` is the SDK architecture, `armv7hf` or `aarch64`.
-
-Copy the result from the container image to a local directory `build`:
-
-```sh
-docker cp $(docker create --platform=linux/amd64 <APP_IMAGE>):/opt/app ./build
-```
-
-The `build` directory contains the build artifacts, where the ACAP application
-is found with suffix `.eap`, depending on which SDK architecture that was
-chosen, one of these files should be found:
-
-- `web_server_rev_proxy_1_0_0_aarch64.eap`
-- `web_server_rev_proxy_1_0_0_armv7hf.eap`
-
-> [!NOTE]
->
-> For detailed information on how to build, install, and run ACAP applications, refer to the official ACAP documentation: [Build, install, and run](https://developer.axis.com/acap/develop/build-install-run/).
-
-#### Install and start the application
-
-Browse to the application page of the Axis device:
-
-```sh
-http://<AXIS_DEVICE_IP>/index.html#apps
-```
-
-1. Click on the tab **Apps** in the device GUI
-2. Enable **Allow unsigned apps** toggle
-3. Click **(+ Add app)** button to upload the application file
-4. Select the newly built application package, depending on architecture:
-
-   - `web_server_rev_proxy_1_0_0_aarch64.eap`
-   - `web_server_rev_proxy_1_0_0_armv7hf.eap`
-
-5. Click **Install**
-6. Run the application by enabling the **Start** switch
-
-#### The expected output
-
-A user can make a HTTP request to the application API using e.g. cURL
-
-```sh
-curl -u <USER>:<PASSWORD> --anyauth http://<AXIS_DEVICE_IP>/local/web_server_rev_proxy/my_web_server
-```
-
-Where the expected output is
-
-```sh
-<html>
- <head><link rel="stylesheet" href="style.css"/></head>
- <title>
-  ACAP Web Server Example
- </title>
- <body>
-  <h1>ACAP Web Server Example</h1>
-  Welcome to the web server example, this server is based on the
-        <a href="https://github.com/civetweb/civetweb">CivetWeb</a> C library.
- </body>
-</html>
-```
-
-To view the rendered web page, click on the `Open` button of the application
-from the `Apps` tab of the device GUI. Alternatively, browse directly to
-`http://<AXIS_DEVICE_IP>/local/web_server_rev_proxy/my_web_server`.
-
-The application log can be found by either
-
-- Browse to `http://<AXIS_DEVICE_IP>/axis-cgi/admin/systemlog.cgi?appname=web_server_rev_proxy`.
-- Browse to the application page and click the `App log`.
-
-## License
-
-**[Apache License 2.0](../LICENSE)**
+- Choose the **reverse proxy** example when you want an embedded web server with flexible routing and easy reuse of existing server-side C code.
+- Choose the **FastCGI** example when you want tighter integration with Apache and a native ACAP web serving flow.