The oai web server is an optional monitoring and debugging tool. Purpose is to give access to oai softmodems functionalities via a web interface. In this first release interface to the telnet server commands and to the softscope are delivered.
The oai web server is an optional monitoring and debugging tool. Purpose is to give access to oai softmodems functionalities via a web interface. In this release interface to the telnet server commands and to the softscope are delivered.
The web server interface is implemented in two parts: a back-end, included in the softmodem process and a front-end which is a browser application.
The oai web server back-end is implemented in a shared library to be loaded by the [oai shared library loader](loader) when `--websrv` option is specified on the command line. `libwebsrv.so ` code is common to all oai softmodem executables, the current release has been tested with the nr UE and the gNB.
The oai web server back-end is implemented in a shared library to be loaded by the [oai shared library loader](../../DOC/loader.md) when `--websrv` option is specified on the command line. `libwebsrv.so` code is common to all oai softmodem executables,
the current release has been tested with the nr UE and the gNB.
The front-end is an [angular](https://angular.io/docs) application. After being built and installed it is delivered to browsers by the back-end at connection time.
Front-end and back-end communicate via http request - http response transactions, including `json` body. these `json` interfaces are defined in the [frontend/src/app/api/XXXX.api.ts](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv/src/frontend/src/app/api/) files. Back-end decapsulates the http requests it receives, looking for the `json`body to determine the requested information or command. Then the back-end builds a http response, with a `json`body encapsulating the requested information or the requested command result.
Front-end and back-end communicate via http request - http response transactions, including `json` body. these `json` interfaces are defined in the [frontend/src/app/api/XXXX.api.ts](../frontend/src/app/api/) files.
Back-end uses a callback machanism to map received http requests to dedicated functions. Typically a callback function decapsulates the http requests it receives, looking for the `json`body to determine the requested information or command. Then the back-end builds a
http response, with a `json`body encapsulating the requested information or the requested command result.
When unsolicited communication, from back-end to front-end is necessary, a [websocket](https://www.rfc-editor.org/rfc/rfc6455) link is opened. This is the case for the softscope interface.
# web server interface source files
web server source files are located in [common/utils/websrv](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv)
web server source files are located in [common/utils/websrv](..)
1. back-end files are directly located in the `websrv` repository
1. The [frontend/src](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv/src/frontend) sub-directory contains the angular front-end source tree.
1.[common/utils/websrv/helpfiles](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv/helpfiles) contains files delivered to the front-end to respond to help requests.
1. The [frontend/src](../frontend/src) sub-directory contains the angular front-end source tree.
1.[common/utils/websrv/helpfiles](../helpfiles) contains files delivered to the front-end to respond to help requests.
Backend devlopment is classical C programming, using [libulfius](https://github.com/babelouest/ulfius/blob/master/API.md) for the web server implementation
and [libjansson](https://jansson.readthedocs.io/en/latest/) for formatting and accessing the JSON http bodies which are used by the angular frontend to exchange data with the server.
The backend processes the http requests coming from the frontend using the ulfius callback mechanism. backend can also send unsollicited data to the frontend using a websocket
Frontend has been developped using the [angular framework](https://angular.io/) which implies TypeScript and HTML programming with the specificity of the node.js libraries and
angular extensions.
Debugging the frontend side may be more difficult than the backend, some tools may help:
- Some IDE such as [vscode](https://code.visualstudio.com/) are "angular aware" and can ease debugging your modifications .
- Setting UTIL log level to informational in the backend and websrv debug flag to 2 ( `--log_config.util_log_level info --websrv.debug 2` ) will trigger backend traces which may help, including the dump of JSON type http content
- Browser devloper tools such as console may also help
There is a dedicated CMakeLists.txt, located in the websrv directory, to build both backend and frontend. Including the websrv option when configuring cmake ( `./build_oai --build-lib websrv` ) is required to be able to include the web server targets in the oai build scripts (either Makefile or ninja).
`libwebsrv.so` shared library is the backend binary. It is possibly dynamically loaded at runtime, which then triggers the execution of the
`websrv_autoinit` function that initializes the http server. Re-building the backend can be done using either `make websrv` or `ninja websrv` and it also re-builds the frontend .
The frontend run-time is made of a set of files generated from the TypeScript, HTML, CSS sources via the npm utility. It also includes some directly edited files such as the helpfiles. Frontend run-time is installed in the `websrv` sub-directory of the build path
(usually `<oai repository>/cmake_targets/ran_build/build`) Re-building frontend can be done via the websrvfront target: `make websrvfront` or `ninja websrvfront`.
###### backend source files
They are all located in the websrv repository
| source file |description |
|---|---|
| websrv.c | main backend file, starts the http server and contains functions for telnet server interface ( softmodem commands tab) |
| websrv.h | the only web server include file, contains utils prototypes, constants definitions, message definitions. Note that it must be kept consistent with frontend, unfortunatly we have not found a way to have common include files between C and javascript |
| websrv_utils.c | utility functions common to all backend sources: dump http request and JSON content. format string response from a file, a C string, a buffer asynchronously loaded. format help from help file |
| websrv_websockets.c | contains functions for the softscope interface (scope tab): initialize, close websocket, dispatch incoming messages, send a websocket message to frontend |
| websrv_scope.c | softscope specific functions: callbacks to process softope frontend request and function to send, receive and process softscope websocket messages |
| websrv_noforms.c websrv_noforms.h | stub functions to help using a common softscope interface for xforms softscope and the webserver softscope, could be removed when improving softscope architecture (don't use interface specific function in nr_physcope.c) |
###### main frontend source files
Frontend directory tree comes from the angular framework. The root of this tree is `websrv/frontend/`. Main sub directories or files are:
-`src/app/api` contains TypeScript files with functions to send http requests to the backend. These functions are used from components sources.
-`src/app/components/<component name>` contains the code (TypeScript, HTML and possibly CSS or XCSS) for a web page, for example the softscope, or popup page used to ask a question or return transaction status.
-`src/app/components/controls` contains TypeScript code used for managing some form fields used in the `softmodem commands` tab.
-`src/app/components/services` contain TypeScript code for utilities such as managing the websocket interface with the backend or downloading a file.
-`src/app/app-routing-module.ts` defines mapping between urls as entered by user and components
-`src/app/app.component.ts``src/app/app.component.html` define the first page displayed to user
-`src/environments` contains environment.<buildtype>.ts file wich defines the `environment` variable depending on the build type. The delivered build scripts are using the `prod` version which has been written to make frontend and backend to interact properly in a production platform. Other build type is to be used in debug environment where frontend is not downloaded from the backend.
-`src/commondefs.ts`: constant definitions common to several TypeScript sources
