From 58db0ef7605c4c7271c86b5aa9b3efb7a47ee4d9 Mon Sep 17 00:00:00 2001 From: Daniel Silhavy Date: Fri, 14 Oct 2022 12:46:34 +0200 Subject: [PATCH 1/8] Add a hint to the documentation to checkout the correct branch for feature development (#38) --- README.md | 46 +++++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index e2ae321..820aa5d 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,34 @@ # 5G-MAG Reference Tools: 5GMS Application Server -This repository holds the 5GMS Application Server implementation for the 5G-MAG -Reference Tools. +This repository holds the 5GMS Application Server implementation for the 5G-MAG Reference Tools. ## Introduction -The 5GMS application server (AS) is a Network Function that forms part of the -5G Media Services framework as defined in ETSI TS 126.501. +The 5GMS application server (AS) is a Network Function that forms part of the 5G Media Services framework as defined in +ETSI TS 126.501. -This implementation is comprised of a small Python daemon process which -implements the 5GMS M3 interface as a simple configuration file that is shared -with the Reference Tools [5GMS AF](https://github.com/5G-MAG/rt-5gms-application-function). +This implementation is comprised of a small Python daemon process which implements the 5GMS M3 interface as a simple +configuration file that is shared with the Reference +Tools [5GMS AF](https://github.com/5G-MAG/rt-5gms-application-function). -The web server or reverse proxy functionality is provided by an external -daemon. This 5GMS AS manages the external daemon by dynamically writing its -configuration files and managing the daemon process lifecycle. At present the -only daemon that can be controlled by the AS is nginx +The web server or reverse proxy functionality is provided by an external daemon. This 5GMS AS manages the external +daemon by dynamically writing its configuration files and managing the daemon process lifecycle. At present the only +daemon that can be controlled by the AS is nginx ([website](https://nginx.org/)). ## Specifications -* [ETSI TS 126 501](https://portal.etsi.org/webapp/workprogram/Report_WorkItem.asp?WKI_ID=66447) - 5G Media Streaming (5GMS): General description and architecture (3GPP TS 26.501 version 17.2.0 Release 17) -* [ETSI TS 126 512](https://portal.etsi.org/webapp/workprogram/Report_WorkItem.asp?WKI_ID=66919) - 5G Media Streaming (5GMS): Protocols (3GPP TS 26.512 version 17.1.2 Release 17) +* [ETSI TS 126 501](https://portal.etsi.org/webapp/workprogram/Report_WorkItem.asp?WKI_ID=66447) - 5G Media Streaming ( + 5GMS): General description and architecture (3GPP TS 26.501 version 17.2.0 Release 17) +* [ETSI TS 126 512](https://portal.etsi.org/webapp/workprogram/Report_WorkItem.asp?WKI_ID=66919) - 5G Media Streaming ( + 5GMS): Protocols (3GPP TS 26.512 version 17.1.2 Release 17) ## Downloading Release sdist tar files can be downloaded from _TBC_. The source can be obtained by cloning the github repository. + ``` git clone --recurse-submodules https://github.com/5G-MAG/rt-5gms-application-server.git ``` @@ -35,22 +36,25 @@ git clone --recurse-submodules https://github.com/5G-MAG/rt-5gms-application-ser ## Building a Python distribution To build a Python sdist distribution tar do the following. + ``` git clone --recurse-submodules https://github.com/5G-MAG/rt-5gms-application-server.git cd rt-5gms-application-server python3 -m build --sdist ``` + The distribution sdist tar file can then be found in the `dist` subdirectory. ## Installing This application can be installed using pip with a distribution sdist tar file: + ``` python3 -m pip install rt-5gms-application-server-.tar.gz ``` -Alternatively, to installing the 5GMS Application Server from the source can be -done using these commands: +Alternatively, to installing the 5GMS Application Server from the source can be done using these commands: + ``` git clone --recurse-submodules https://github.com/5G-MAG/rt-5gms-application-server.git cd rt-5gms-application-server @@ -59,18 +63,22 @@ python3 -m pip install . ## Running -Once [installed](#Installing), the application server can be run using the -following command syntax: +Once [installed](#Installing), the application server can be run using the following command syntax: + ``` Syntax: 5gms-application-server [-c ] ``` Command line help can be obtained using the -h flag: + ``` 5gms-application-server -h ``` ## Development -Please see the [docs/README.md](docs/README.md) file for project development -and testing information. +This project follows +the [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). The `development` +branch of this project serves as an integration branch for new features. Consequently, please make sure to switch to the `development` +branch before starting the implementation of a new feature. Please check the [docs/README.md](docs/README.md) file for +further project development and testing information. From 33cbcbe48911c98a858d21ea328931082e33c89c Mon Sep 17 00:00:00 2001 From: David Waring Date: Wed, 19 Oct 2022 11:57:45 +0100 Subject: [PATCH 2/8] Intercept build backend calls to ensure openapi modules are built. Intercepts all standard build backend functions and runs checks to ensure that the OpenAPI bindings have been built. This fixes issues where rt_5gms_as.openapi_5g was not being included in some distributions or installs. --- build_scripts/backend.py | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/build_scripts/backend.py b/build_scripts/backend.py index 5fb0e21..6df4f75 100644 --- a/build_scripts/backend.py +++ b/build_scripts/backend.py @@ -21,7 +21,11 @@ from setuptools import build_meta as _orig import subprocess -replace = ['build_sdist'] +replace = ['build_sdist', + 'build_wheel', + 'get_requires_for_build_sdist', + 'get_requires_for_build_wheel', + 'prepare_metadata_for_build_wheel'] log = logging.getLogger(__name__) # Copy all exported variables from the original @@ -48,3 +52,21 @@ def _check_openapi(): def build_sdist(sdist_directory, config_settings=None): _check_openapi() return _orig.build_sdist(sdist_directory, config_settings) + +def build_wheel(wheel_directory, config_settings=None, metadata_directory=None): + _check_openapi() + return _orig.build_wheel(wheel_directory, config_settings, + metadata_directory) + +def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None): + _check_openapi() + return _orig.prepare_metadata_for_build_wheel(metadata_directory, + config_settings) + +def get_requires_for_build_sdist(config_settings=None): + _check_openapi() + return _orig.get_requires_for_build_sdist(config_settings) + +def get_requires_for_build_wheel(config_settings=None): + _check_openapi() + return _orig.get_requires_for_build_wheel(config_settings) From d98f88d47e1c57635cda772524e79e57fcaec84f Mon Sep 17 00:00:00 2001 From: David Waring Date: Wed, 19 Oct 2022 12:07:19 +0100 Subject: [PATCH 3/8] Update documentation. Updates the developer documentation to include new files and to change the names of renamed files in this project. Include information in the main README to make it clear that the application requires root privileges to run when used with the default configuration. --- README.md | 2 ++ docs/README.md | 29 ++++++++++++++++------------- 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 820aa5d..6666eaa 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,8 @@ Command line help can be obtained using the -h flag: 5gms-application-server -h ``` +Please note that the default configuration will require the application server to be run as the root user as it uses the privileged port 80 and stores logs and caches in root owned directories. If you wish to run this as an unprivileged user you will need to follow the instructions for creating and using an alternative configuration file. These instructions can be found in the [development documentation](docs/README.md#running-the-example-without-building). + ## Development This project follows diff --git a/docs/README.md b/docs/README.md index a14b240..863a071 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,19 +5,23 @@ In this directory you will find files to assist with development and testing of the 5G-MAG Reference Tools 5GMS Application Server (AS). Files in this repository: -- README.md - Project README file. -- LICENSE - The software license for this project. -- pyproject.toml - The Python project description for building and installing the application. -- build_scripts/ - Scripts used when building the python project. +- ATTRIBUTION_NOTICE - Project run-time attributions +- LICENSE - The software license for this project. +- README.md - Project README file. +- pyproject.toml - The Python project description for building and installing the application. +- build_scripts/ - Scripts used when building the python project. - backend.py - build backend wrapper to trigger extra build actions. - - generate_openapi - Will generate the OpenAPI python modules if not already present. -- docs/ - Development documentation and examples. + - generate_5gms_as_openapi - Will generate the OpenAPI python modules if not already present. +- docs/ - Development documentation and examples. - README.md - This document. - chc.json - An example ContentHostingConfiguration JSON file which provisions a pull-ingest AS for "Big Buck Bunny". -- src/ - The application source modules. - - rt_5gms_as - The main Python module for this application +- external/ - Directory containing submodule mount points. + - rt-common-shared/ - The common shared examples and scripts. +- src/ - The application source modules. + - rt_5gms_as/ - The main Python module for this application - app.py - Application entry point. - - openapi_5g - Python bindings generated by openapi-generator-cli from the 5G APIs. Note: This directory is not present in the tree until `build_scripts/generate_openapi` is run. + - context.py - module for the application Context class. + - openapi_5g/ - Python bindings generated by openapi-generator-cli from the 5G APIs. Note: This directory is not present in the tree until `build_scripts/generate_openapi` is run. - proxy_factory.py - Factory module to pick a suitable web server/proxy. - proxies/ - Contains the web server/proxy detection and configuration classes and any data files they need. - utils.py - Common utility functions for the web server/proxy classes. @@ -32,7 +36,7 @@ Generate the OpenAPI python modules (these are not part of the source distribution): ``` cd rt-5gms-application-server -build_scripts/generate_openapi +build_scripts/generate_5gms_as_openapi ``` Create a configuration to run the application server as a local, unprivileged, @@ -68,8 +72,7 @@ This will start nginx with a configuration which will provide a reverse proxy to Regenerating the 5G API bindings -------------------------------- -The `build_scripts/generate_openapi` script will use wget, git and java to -download the openapi-generator tool, the 5G OpenAPI YAML and generate the `rt_5gms_as.openapi_5g` Python module package. The script will only do this if the +The `build_scripts/generate_5gms_as_openapi` script will use wget, git and java to download the openapi-generator tool, the 5G OpenAPI YAML and generate the `rt_5gms_as.openapi_5g` Python module package. The script will only do this if the `src/rt_5gms_as/openapi_5g` directory does not already exist. Therefore to regenerate the API bindings you first need to remove the old bindings: @@ -80,7 +83,7 @@ rm -rf src/rt_5gms_as/openapi_5g Then run the generator script: ``` -rt-5gms-application-server/build_scripts/generate_openapi +rt-5gms-application-server/build_scripts/generate_5gms_as_openapi ``` For reference (or if it is desirable to recreate the steps manually) the `generate_openapi` script performs the following actions: From d9ce3eaa0938b63e52399c42edb967a2273b9b06 Mon Sep 17 00:00:00 2001 From: David Waring Date: Wed, 19 Oct 2022 12:07:43 +0100 Subject: [PATCH 4/8] Use latest rt-common-shared. --- external/rt-common-shared | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/external/rt-common-shared b/external/rt-common-shared index 1c9da6e..5bb7f8b 160000 --- a/external/rt-common-shared +++ b/external/rt-common-shared @@ -1 +1 @@ -Subproject commit 1c9da6e17b44fbec80fd7420a8e93c308a003fce +Subproject commit 5bb7f8bb7ac0ee0e39f44340424d8e31997d1ce6 From 4faa7111bf61024b83b2c3cb4d0951ecc8b2387a Mon Sep 17 00:00:00 2001 From: David Waring Date: Wed, 19 Oct 2022 12:08:39 +0100 Subject: [PATCH 5/8] Include the ATTRIBUTION_NOTICE in distributed documentation. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 7a59928..e24d8b1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,5 +30,5 @@ where = ["src"] "rt_5gms_as.proxies" = ["*.tmpl"] [tool.setuptools.data-files] -'share/doc/rt-5gms-application-server' = ['docs/*'] +'share/doc/rt-5gms-application-server' = ['docs/*', 'ATTRIBUTION_NOTICE'] 'share/doc/rt-5gms-application-server/examples' = ['external/rt-common-shared/5gms/examples/*'] From 9af117dfe79a34cb8eeafd3528de9828cf004db4 Mon Sep 17 00:00:00 2001 From: "Jordi J. Gimenez" <87380947+jordijoangimenez@users.noreply.github.com> Date: Wed, 19 Oct 2022 14:09:31 +0200 Subject: [PATCH 6/8] Correction ../docs/rt-common-shared/5gms/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json is under ../external/ --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 863a071..0dd6079 100644 --- a/docs/README.md +++ b/docs/README.md @@ -65,7 +65,7 @@ mkdir /tmp/rt-5gms-as/logs Run the example directly: ``` cd rt-5gms-application-server/src -python3 -m rt_5gms_as.app ../docs/rt-common-shared/5gms/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json +python3 -m rt_5gms_as.app ../external/rt-common-shared/5gms/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json ``` This will start nginx with a configuration which will provide a reverse proxy to the Big Buck Bunny DASH media at . From c657ab4e6158f896618b370b87c8f7dd33fd50e6 Mon Sep 17 00:00:00 2001 From: David Waring Date: Wed, 19 Oct 2022 13:51:57 +0100 Subject: [PATCH 7/8] Bump version number for release. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index e24d8b1..c9817d4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ backend-path = ["build_scripts"] [project] name = "rt-5gms-application-server" -version = "0.0.1" +version = "1.0.0" dependencies = [ 'urllib3 >= 1.25.3', 'python-dateutil', From 41fe62bd20665ad2b11cd88448a8ca2d9a6a25c3 Mon Sep 17 00:00:00 2001 From: David Waring Date: Wed, 19 Oct 2022 14:02:54 +0100 Subject: [PATCH 8/8] Fix configurations examples list in the developer documentation. This removes the description for chc.json, which has now moved to rt-common-shared and adds a description for the example application configuration file. --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 0dd6079..929dd02 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,7 @@ Files in this repository: - generate_5gms_as_openapi - Will generate the OpenAPI python modules if not already present. - docs/ - Development documentation and examples. - README.md - This document. - - chc.json - An example ContentHostingConfiguration JSON file which provisions a pull-ingest AS for "Big Buck Bunny". + - example-application-server.conf - An application configuration which documents the defaults and meaning for each application configuration option. - external/ - Directory containing submodule mount points. - rt-common-shared/ - The common shared examples and scripts. - src/ - The application source modules.