websrvdev.md

enhancing the web server

development platform

Backend devlopment is classical C programming, using libulfius for the web server implementation and libjansson 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 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 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..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

oai web serverinterface home