Patchset 2: Clean-up.
Issue-ID: NONRTRIC-771
Change-Id: I65f4ac760d52c8579fdbf2773fa595b60d413c9a
Signed-off-by: halil.cakal <halil.cakal@est.tech>
.coverage
coverage.xml
htmlcov/
+
+# Python virtual env
+venv/
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2022 Nordix
+
+.. |nbsp| unicode:: 0xA0
+ :trim:
+
+.. |nbh| unicode:: 0x2011
+ :trim:
+
+=====================
+Callout Server
+=====================
+
+API Documentation
+=================
+
+The O-RAN SC external server is an extension for Near-RealTime RIC simulator. It creates an external web server building RESTful API. It is capable of recieving Rest calls from the northbound simulator version STD_2.0.0 and responses back to it.
+
+The details of API definitions are being explained below:
+
+.. Generates content from EXT_SRV_api.yaml
+.. openapi:: ../near-rt-ric-simulator/test/EXT_SRV/api/EXT_SRV_api.yaml
+
+
+Admin Functions
+================
+
+Health Check
+------------
+
+GET
++++
+
+Returns the status of the external server.
+
+**URL path:**
+ /
+
+**Parameters:**
+ None.
+
+**Responses:**
+ 200:
+ OK
+
+**Examples:**
+
+**Call**: ::
+
+ curl -X GET "http://localhost:9095/"
+
+**Result**:
+
+200: ::
+
+ OK
+
+
+Delete all policy instances in external server
+----------------------------------------------
+
+POST
+++++
+
+Delete all policy instances.
+
+**URL path:**
+
+/serveradmin/deleteinstances
+
+**Parameters:**
+
+None.
+
+**Responses:**
+
+200:
+
+All a1 policy instances deleted
+
+**Examples:**
+
+**Call**: ::
+
+ curl -X POST "http://localhost:9095/serveradmin/deleteinstances"
+
+**Result**:
+
+200: ::
+
+ All a1 policy instances deleted
+
+
+Response manipulation
+---------------------
+It is possible to manipulate the response of all operations on the external server
+
+POST
+++++
+
+Force a specific response code for the all (the next) external server operation. Unless it is reset, it will always respond the same response code back.
+
+**URL path:**
+
+/serveradmin/forceresponse?code=<http-response-code>
+
+**Parameters:**
+
+code: (*Required*)
+
+The HTTP response code to return.
+
+**Responses:**
+
+200:
+
+Force response code: <expected code> set for all external server response until it is resetted
+
+**Examples:**
+
+**Call**: ::
+
+ curl -X POST "http://localhost:9095/serveradmin/forceresponse?code=500"
+
+**Result**:
+
+200: ::
+
+ Force response code: 500 set for all external server response until it is resetted
+
+
+Reset response-manipulation
+---------------------------
+It is possible to reset the response manipulation on the external server
+
+POST
+++++
+
+Clears specific response code for all (the next) external server operation.
+
+**URL path:**
+
+/serveradmin/forceresponse?code=<http-response-code>
+
+**Parameters:**
+
+code: (*Required*)
+
+The HTTP response code to return.
+
+**Responses:**
+
+200:
+
+Force response code has been resetted for all external server responses
+
+**Examples:**
+
+**Call**: ::
+
+ curl -X POST "http://localhost:9095/serveradmin/forceresponse?code=500"
+
+**Result**:
+
+200: ::
+
+ Force response code has been resetted for all external server responses
+
+
+Response time manipulation
+--------------------------
+It is possible to set a period of time to delay response time.
+
+POST
+++++
+
+Force delayed response of all A1 responses. The setting will remain until the delay is set to '0'
+
+**URL path:**
+
+/serveradmin/forcedelay?delay=<delay-time-seconds>
+
+**Parameters:**
+
+delay: (*Required*)
+
+The time in seconds to delay all responses.
+
+**Responses:**
+
+200:
+
+Force delay: <expected_delay> sec set for all external server responses until it is resetted
+
+**Examples:**
+
+**Call**: ::
+
+ curl -X POST "http://localhost:9095/serveradmin/forcedelay?delay=5"
+
+**Result**:
+
+200: ::
+
+ Force delay: 5 sec set for all external server responses until it is resetted
+
+
+Reset response time manipulation
+--------------------------------
+It is also possible to reset delay response time.
+
+POST
+++++
+
+The setting will clear the delay.
+
+**URL path:**
+
+/serveradmin/forcedelay
+
+**Parameters:**
+
+None.
+
+The time in seconds to delay all responses.
+
+**Responses:**
+
+200:
+
+Force delay has been resetted for all external server responses
+
+**Examples:**
+
+**Call**: ::
+
+ curl -X POST "http://localhost:9095/serveradmin/forcedelay"
+
+**Result**:
+
+200: ::
+
+ Force delay has been resetted for all external server responses
from docs_conf.conf import *
+language = 'en'
+
linkcheck_ignore = [
'http://localhost.*',
'http://127.0.0.1.*',
'https://gerrit.o-ran-sc.org.*'
]
+
+extensions = [
+ 'sphinxcontrib.openapi',
+]
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
-.. Copyright (C) 2021 Nordix
+.. Copyright (C) 2021-2022 Nordix
.. |nbsp| unicode:: 0xA0
:trim:
./overview.rst
./simulator-api.rst
+ ./callout-server.rst
./release-notes.rst
Note that test can be performed both using the nonsecure http port and the secure https port.
-Build and start the simulator container using:
+Build and start the simulator containers: STD_1.1.3 and OSC_2.1.0, using:
./build\_and\_start.sh duplicate-check|ignore-duplicate
+Build and start the simulator container: STD_2.0.0, using:
+
+./build\_and\_start.sh duplicate-check|ignore-duplicate ext-srv|ext-srv-secure|ignore-ext-srv
+
+STD_2.0.0 version is now including an external server that is a Python server building RESTful API. The external server supports HTTP/HTTPS protocols.
+The description of the start parameters are explained below:
+ext-srv: Runs external server that supports HTTP protocol only.
+ext-srv-secure: Runs external server that supports HTTPS protocol as well.
+ignore-ext-srv: Ignores external server to run.
This will build and start the container in interactive mode. The built container only resides in the local docker repository.
Note, the default port is 8085 for http and 8185 for https. When running the simulator as a container, the defualt ports can be re-mapped to any port on the localhost.
-In a second terminal, go to the same folder and run the basic test script, basic\_test.sh nonsecure|secure or commands.sh nonsecure|secure duplicate-check|ignore-duplicate
+In a second terminal, go to the same folder and run the basic test script, basic\_test.sh nonsecure|secure or commands.sh nonsecure|secure duplicate-check|ignore-duplicate for STD_1.1.3 and OSC_2.1.0 versions.
+
+For the STD_2.0.0 version, in a second terminal, go to the same folder and run the basic test script like:
+./basic_test.sh nonsecure|secure duplicate-check|ignore-duplicate ext-srv|ext-srv-secure|ignore-ext-srv
+The description of the test script parameters are explained below:
+nonsecure|secure: Runs test cases with either support of HTTP/HTTPS protocol.
+duplicate-check|ignore-duplicate: Runs test cases with either support of duplicate/ignore-duplicate flag for the policies.
+ext-srv|ext-srv-secure|ignore-ext-srv: If the simulator started with ext-srv or ext-srv-secure parameter, then one of these options can be used. Otherwise, ignore-ext-srv parameter should be used.
Note that the arg for duplicate check must match in both scripts.
This script runs a number of tests towards the simulator to make sure it works properply.
Navigate to 'near-rt-ric-simulator/tests'. Choose the version to test and use that file for test.
-Use 'python3 -m pytest \<filename>' to run unit test only with no coverage check
+Use 'python3 -m pytest \<filename>' to run unit test only with no coverage check. Before running that command, the dependencies which are pytest and connexion should be installed in your virtual environment. If the latest connexion version arises DeprecationWarning, you may try to install connexion with version 2.6.0.
Or use 'coverage run -m pytest \<filename>' to run unit test and produce coverage data.
--- /dev/null
+# Documentation
+.idea/
+.tox
+docs/_build/
+.DS_STORE
+
+# IDE
+.project
+.vscode
+
+.coverage
+coverage.xml
+htmlcov/
+
+# Python virtual env
+venv/
--- /dev/null
+# O-RAN-SC External Server extension for Near-RealTime RIC Simulator
+
+The O-RAN SC external server is an extension for Near-RealTime RIC simulator. It creates an external web server building RESTful API. It is capable of recieving Rest calls from the northbound simulator version and responses back to it.
+
+The external server supports GET, PUT and DELETE operations (version of the open API yaml file\):
+
+| Yaml file version | Version id |
+| --------------------- | ------------------- |
+| EXT_SRV_api.yaml | 0.0.1 |
+
+The overall folder structure is \(relative to the location of this README file\):
+
+| Dir | Description |
+| ---------------- | ----------- |
+|. |Dockerfile, tox.ini and README |
+|api |The open api yaml |
+|src |Python source code |
+|certificate |A self-signed certificate and a key |
+|docs |Auto generated API descriptions in HTML format |
+
+The external server handles the requests that are defined in the open API yaml file. All these requests are implemented in the server.py file in the src folder. In addition, a number of administrative functions are also supported and implemented by the main.py in the source folder.
+
+The section below outlines the supported open api rest-based operations as well as the adminstrative operations.
+
+# Ports and certificates
+
+The external server normally opens the port 9095 for http. If a certificate and a key are provided the external server will open port 9195 for https instead. The port 9195 is only opened if a valid certificate and key is found.
+The certificate and key shall be placed in the same directory and the directory shall be mounted to /usr/src/app/cert in the container.
+
+| Port | Protocol |
+| -------- | ----- |
+| 9095 | http |
+| 9195 | https |
+
+The directory certificate contains a self-signed cert. Use the script generate_cert_and_key.sh to generate a new certificate and key. The password of the certificate must be set 'test'.
+The same urls are availables on both the http port 9095 and the https port 9195. If using curl and https, the flag -k shall be given to make curl ignore checking the certificate.
+
+# Supported operations in External Server 0.0.1
+
+
+For the complete yaml specification, see [openapi.yaml](../api/EXT_SRV_api.yaml)
+
+URIs for server:
+
+| Function | Path and parameters |
+| --------------------- | ------------------- |
+| GET, Get all A1 policy ids | localhost:9095/a1policies |
+| GET, Query for an A1 policy | localhost:9095/a1policy/{a1policyId} |
+| PUT, Create an A1 policy | localhost:9095/a1policy/{a1policyId} |
+| DELETE, Delete an A1 policy | localhost:9095/a1policy/{a1policyId} |
+
+URIs for admin operations:
+
+| Function | Path and parameters |
+| --------------------- | ------------------- |
+| POST, Delete all A1 policy instances | localhost:9095/serveradmin/deleteinstances |
+| POST, Force a specific response code for all A1 operation | localhost:9095/serveradmin/forceresponse?code=500 |
+| POST, Reset force response code | localhost:9095/serveradmin/forceresponse |
+| POST, Force delayed response of all A1 operations | localhost:9095/serveradmin/forcedelay?delay=5 |
+| POST, Reset force delayed response | localhost:9095/serveradmin/forcedelay |
+
+
+## License
+
+Copyright (C) 2022 Nordix Foundation.
+Licensed under the Apache License, Version 2.0 (the "License")
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+For more information about license please see the [LICENSE](LICENSE.txt) file for details.
openapi: 3.0.0
info:
title: 'External Server for A1 simulator'
- version: 2.0.0
+ version: 0.0.1
description: |
External test server.
© 2022, O-RAN Alliance.
All rights reserved.
externalDocs:
description: 'An external server building CRUD RestFUL APIs which is provisioned by A1 simulator. It will be a refrence point for the callouts'
- url: 'https://www.testserver/specifications'
+ url: 'https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/external-server.html'
servers:
- url: '{apiRoot}'
variables:
apiRoot:
- default: 'https://testserver.com'
+ default: 'http://www.example.com'
paths:
'/a1policies':
get:
--- /dev/null
+from docs_conf.conf import *
+
+language = 'en'
+
+extensions = [
+ 'sphinxcontrib.openapi',
+]
+
+linkcheck_ignore = [
+ 'http://localhost.*',
+ 'http://127.0.0.1.*',
+ 'https://gerrit.o-ran-sc.org.*'
+]
--- /dev/null
+---
+project_cfg: oran
+project: sim-a1-interface
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2022 Nordix
+
+.. _ext-srv-api:
+
+==========================
+External Server API
+==========================
+
+.. Generates content from EXT_SRV_api.yaml
+.. openapi:: ../api/EXT_SRV_api.yaml
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2022 Nordix
+
+.. |nbsp| unicode:: 0xA0
+ :trim:
+
+.. |nbh| unicode:: 0x2011
+ :trim:
+
+.. _a1-interface-ext-srv:
+
+======================
+A1 Interface EXT SRV
+======================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ ./overview.rst
+ ./ext-srv-api.rst
+ ./release-notes.rst
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 Nordix
+
+.. |nbsp| unicode:: 0xA0
+ :trim:
+
+.. |nbh| unicode:: 0x2011
+ :trim:
+
+
+A1 Simulator EXT SRV
+=====================
+
+The A1 Simulator terminates the A1 interface and provides a way to test Non-RT RIC services without the need to deploy Near |nbh| RT |nbsp| RICs.
+
+Apart from providing the A1 API, the simulator also provides an administrative API to manage policy types and manipulate
+the simulator, see ":ref:`ext-srv-api`".
+
+The A1 Simulator supports running multiple simulations using different versions of the A1 Application protocol, and supports realistic stateful simulation of A1 Enrichment Information and A1 Policy behaviours.
+
+For information on how to run the simulator, see the *README.md* file in the repository.
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix
+
+=============
+Release-Notes
+=============
+
+
+This document provides the release notes for the release of the Near-RT RIC A1 Interface Simulator.
+
+.. contents::
+ :depth: 3
+ :local:
+
+
+Version history Near-RT RIC A1 Interface Simulator
+==================================================
+
++------------+----------+------------------+----------------+
+| **Date** | **Ver.** | **Author** | **Comment** |
+| | | | |
++------------+----------+------------------+----------------+
+| 2022-06-29 | 2.3.0 | Halil Cakal | F Release |
+| | | | |
++------------+----------+------------------+----------------+
+
+Release Data
+============
+
+F Release
+---------
++-----------------------------+-------------------------------------------------------+
+| **Project** | Non-RT RIC |
+| | |
++-----------------------------+-------------------------------------------------------+
+| **Repo/commit-ID** | a1-interface/595506e290356d26b8eebfab32ef8d3f625cbb0a |
+| | |
++-----------------------------+-------------------------------------------------------+
+| **Release designation** | F |
+| | |
++-----------------------------+-------------------------------------------------------+
+| **Release date** | 2022-06-29 |
+| | |
++-----------------------------+-------------------------------------------------------+
+| **Purpose of the delivery** | Added Callout hooks towards external server for |
+| | create and delete operations |
+| | |
++-----------------------------+-------------------------------------------------------+
--- /dev/null
+# ==================================================================================
+# Copyright (c) 2022 Nordix
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==================================================================================
+
+[tox]
+envlist = docs,docs-linkcheck
+minversion = 2.0
+skipsdist = true
+
+# doc jobs
+[testenv:docs]
+whitelist_externals = echo
+# Version 3.8 is required, otherwise AttributeError will arise
+basepython = python3.8
+deps =
+ sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ # Version 0.6.0 is required, otherwise BlockGrammer error will arise
+ sphinxcontrib-openapi==0.6.0
+ recommonmark
+ lfdocs-conf
+commands =
+ sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+ echo "Generated docs available in {toxinidir}/docs/_build/html"
+
+[testenv:docs-linkcheck]
+skipsdist = true
+basepython = python3.8
+deps = sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ # Version 0.6.0 is required, otherwise BlockGrammer error will arise
+ sphinxcontrib-openapi==0.6.0
+ recommonmark
+ lfdocs-conf
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
# ==================================================================================
-# Copyright (c) 2020 Nordix
+# Copyright (c) 2020-2022 Nordix
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# doc jobs
[testenv:docs]
whitelist_externals = echo
-basepython = python3
+basepython = python3.8
deps =
sphinx
sphinx-rtd-theme
sphinxcontrib-httpdomain
+ sphinxcontrib-openapi==0.6.0
recommonmark
lfdocs-conf
commands =
[testenv:docs-linkcheck]
skipsdist = true
-basepython = python3
+basepython = python3.8
deps = sphinx
sphinx-rtd-theme
sphinxcontrib-httpdomain
+ sphinxcontrib-openapi==0.6.0
recommonmark
lfdocs-conf
commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
Code Review / sim / a1-interface.git / commitdiff
