Redirecting backend REST and WebSocket communication during URCap development

Introduction

When developing both frontend and backend contributions, you can redirect all REST and WebSocket traffic to a different server without modifying your backend code. This configurable proxy feature can ease the development and integration of components and easily be removed after development. Examples include:

The URCap is running on a robot, to enable debugging, the backend server is running in an IDE on a developer PC
The URCap is running in simulation, to enable the frontend to access robot specific resources, such as tool connector or USB hotplug, the backend is running on a robot.
The URCap is running in simulation and the backend is running directly on a PC host.

Configuration

Enabling redirection is done in the URCap manifest file, specifically in the container.ingress section, using the devUrl key.

Case 1: Running a URCap on the robot and directing REST/WS traffic to an IDE running on another host

The following example enables all traffic in the simple-docker sample to be redirected to a server running at port 5000 on a development machine with IP address 10.52.4.26.

Step 1: Configure URCap and reinstall on the robot

Add the devUrl to the URCaps manifest and reinstall the URCap on the robot.

containers:
  - id: "simple-docker-backend"
    image: "simple-docker-backend:latest"
    ingress:
    - id: rest-api
      containerPort: 5000
      protocol: http
      proxyUrl: /
      devUrl: http://10.52.4.26:5000
    mounts:
    - mount: persistent:/mount
      access: rw

Note

Undoing the redirection is as simple as commenting out the devUrl line above

Step 2: Run the simple-docker backend (simple-rest-api.py) from and IDE on the developer machine

In this specific case, special attention is needed when running the simple-docker-backend python server from an IDE:

proxyUrl

As can be seen above, the server running in the container is using the “proxyUrl” feature. When PolyScope X starts a backend container contribution the proxyUrl conveniently maps the long unique container URL to something simpler inside the contribution container, in this case universal-robots/simple-docker/simple-docker-backend/rest-api is mapped to /. We must compensate for this when running the server in an IDE outside of the URCap container either by not using proxyUrl or making a change in the code running in the IDE. In simple-rest-api.py it could look like this:

...
PROXY_URL_PREFIX = "/universal-robots/simple-docker/simple-docker-backend/rest-api"
@app.route(PROXY_URL_PREFIX+"/", methods=["GET"])
...
@app.route(PROXY_URL_PREFIX+"/", methods=["POST"])
...

Container resources

In the above manifest snippet we can see that the backend container will create a /mount mount point inside the container. When running outside the container we can either create this folder manually or use a different file path in the code. In simple-rest-api.py this could look like:

...
#data_file = "/mount/data.txt"
data_file = "/my/path/data.txt"
...

After taking care of these details, run the Python Flask server on port 5000.

Case 2 Running a URCap in simulation and directing REST/WS traffic to an backend URCap running on a robot

These are almost the same steps as in case 1. Again the example URCap is the simple-docker sample, this time installed in the simulator. REST/WS traffic is redirected to a backend URCap running on a robot with IP address 10.54.4.231

Step 1: Configure URCap and reinstall in the simulator

Add the devUrl to the URCaps manifest and reinstall the URCap in the simulator.

containers:
  - id: "simple-docker-backend"
    image: "simple-docker-backend:latest"
    ingress:
    - id: rest-api
      containerPort: 5000
      protocol: http
      proxyUrl: /
      devUrl: http://10.54.4.231/universal-robots/simple-docker/simple-docker-backend/rest-api/
    mounts:
    - mount: persistent:/mount
      access: rw

Step 2: Install URCap on the robot

Note: In this case, the URCap installed on the robot does not need the devUrl parameter.

Case 3 Running a URCap in simulation and directing REST/WS traffic to an IDE on the developer PC host

When developing a URCap in simulation it might be convenient to develop the backend outside the URCap docker container. This example enables all traffic in the simple-docker sample to be redirected from the simulator to a server running on the simulator host at port 5000.

Step 1: Configure URCap and reinstall in the simulator

Add the devUrl to the URCaps manifest and reinstall the URCap in the simulator.

containers:
  - id: "simple-docker-backend"
    image: "simple-docker-backend:latest"
    ingress:
    - id: rest-api
      containerPort: 5000
      protocol: http
      proxyUrl: /
      devUrl: http://10.52.4.26:5000
    mounts:
    - mount: persistent:/mount
      access: rw

Step 2: Run the simple-docker backend (simple-rest-api.py) from and IDE on the simulator host machine

When running a backend URCap contribution outside of its contribution container, it is needed to compensate for the URCap container features not available outside the container. See Case 1 - Step 2 on how to do that for the simple-docker backend. Finally, run the Python Flask server on port 5000 on the simulator host.