StressAnAPI v1.0.0

.gitignore

@@ -0,0 +1,169 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+backup
+*test*
+*ansi*
+geoip*
+activate
+backup*
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ricardo Abuchaim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,142 @@
+# StressAnAPI v1.0.0
+
+StressAnAPI is a Pure Python application for stress testing on APIs. Easily configurable via command line. Use the arrow keys to increase speed and bursts, see results, requests per seconds and much more.
+
+![](https://raw.githubusercontent.com/rabuchaim/StressAnAPI/main/images/stressanapi.gif)
+
+## Installation
+
+```
+pip install stressanapi
+```
+
+A script file will be installed in /usr/local/bin/stressanapi and you can run the application from any path just typing ```stressanapi```.
+
+
+![](https://raw.githubusercontent.com/rabuchaim/StressAnAPI/main/images/stressanapi-01.png)
+
+
+**StressAnAPI is Pure Python**, so it will not install any libraries on your system. The entire source (1 single file) will be placed in ```/usr/local/lib/python3.XX/dist-packages/stressanapi```
+
+Along with the application, there is also an API server for testing made with Tornado. To use this test server, simply run ```simple_stressanapi_server``` and install the Tornado library with ```pip install tornado```. But that's only if you want to use our little server to test StressAnAPI. This server only binds to IP 127.0.0.1, port 8000 and accepts any method (GET, POST, PUT, PATCH and DELETE) from the API root ```http://localhost:8000/anything_you_want```, and simply returns an "OK". 
+
+```bash
+# simple_stressanapi_server
+To use the simple_stressanapi_server.py you need the 'tornado' library. Run: pip install tornado
+
+# pip install tornado
+Collecting tornado
+Installing collected packages: tornado
+Successfully installed tornado-6.4.1
+
+# simple_stressanapi_server.py
+2024/07/08 23:57:10 >>> Tornado Server is listening on http://127.0.0.1:8000/
+2024/07/08 23:57:10   > Run with --log to enable pretty_logging().
+2024/07/08 23:57:15   > Average Requests: 975 per second
+2024/07/08 23:57:20   > Average Requests: 1129 per second
+2024/07/08 23:57:25   > Average Requests: 2655 per second
+2024/07/08 23:57:30   > Average Requests: 3549 per second
+(...)
+```
+
+## The Configuration File
+
+The configuration file is based on the json format and requires a minimum of 2 keys, the "url" and the "method". It's the basics for you to start testing your API.
+
+```
+{
+    "url":"http://127.0.0.1:8000/api/v1/foo_action",
+    "method":"GET"
+}
+```
+
+> *The json file is not like a Python dictionary, it is similar, but it requires double quotes in the names of keys and values, it does not accept extra commas, and the first line must have only a curly bracket '{', and the last line must have only the closing of the initial curly bracket '}'. When in doubt, create the configuration file in Visual Studio Code, and the syntax highlight will show you if there are errors.*
+
+There are more options that can be configured, to see them just type the ```--template``` command. This option already shows a valid json file, just change it according to your needs and/or remove what you don't want to customize.
+
+```bash
+# stressanapi --template
+```
+
+```
+{
+   "url": "http://localhost:8000/api/v1/foo_action",
+   "method": "GET|POST|PUT|PATCH|DELETE",
+   "post_data": {
+      "id": "my_customer_id",
+      "name": "spécial_çhärs",
+      "token": "mysupertoken"
+   },
+   "headers": {
+      "User-Agent": "StressAnAPI v1.0.0",
+      "Host": "set_your_api_hostname_here",
+      "Content-Type": "application/json",
+      "X-Forwarded-For": "1.2.3.4",
+      "X-Forwarded-Host": "1.2.3.4",
+      "X-Real-IP": "1.2.3.4"
+   },
+   "timeout": 1,
+   "success_status_codes": [
+      200,
+      201,
+      202,
+      204
+   ],
+   "user_agent": "StressAnAPI v1.0.0",
+   "start_interval": 0.5,
+   "start_burst": 1,
+   "start_threads": 1,
+   "cpu_affinity": [-1]
+}
+```
+- **`url`**: I think this field is self-explanatory, right?
+- **`method`**: Enter the method you want to test within the available GET, POST, PUT, PATCH and DELETE
+- **`post_data`**: These are the values ​​you want to post to the API. In this version, only key and value will be accepted. If you inform the GET method, these post_data values ​​will be ignored and will not be sent in API requests.
+- **`headers`**: Enter the headers you want to send to your API. The `content-type` is an important header. Headers are sent in any method.
+- **`timeout`**: Enter the timeout you want to work. The application does not make retries. You can increase/decrease the timeout using the + and - keys on your keyboard to test an ideal and safe timeout value to configure on your API proxy server.
+- **`success_status_codes`**: Enter the status_codes that you consider "success" to return from your API for the call you configured. This information is important in generating statistics, where only the methods reported here are considered successful. If you omit this field, by default, status codes 200, 201, 202 and 204 will be considered successful.
+- **`user_agent`**: If this field is omitted, the default user-agent "StressAnAPI v1.0.0" will be used.
+- **`start_interval`**: Enter the interval between one request and another. This is necessary to allow you to increase/decrease the speed of requests and evaluate how your API behaves with an increase in requests and their impacts. By default, there is a 1 second interval between each request. You can decrease/increase this interval anytime using the UP and DOWN keys on your keyboard.
+- **`start_burst`**: Burst is the number of requests before an interval. You can increase and decrease the burst using the RIGHT and LEFT keys on your keyboard. By default, the application makes 1 request + interval. You can increase it to 2 requests + interval, 10 requests + interval, and so on...
+- **`start_threads`**: This value simulates user concurrency in your API. Use with caution. You can increase/decrease the number of threads using the < and > keys on your keyboard.
+- **`cpu_affinity`**: This is a very important option. If you omit this value, Python will use any processor and you will have concurrency in the stress test. To test the best performance of your API together with StressAnAPI, I suggest defining a CPU core to be used here. If you set the value '-1', the application will inform the Linux operating system to isolate the stressanapi.py process on the last available processor. Do a test without using this option, and then using this option, you will see that it is possible to obtain more requests if you isolate stressanapi on a single CPU core. The same thing with the API server, always leave it isolated in a core all to itself and performance will be much higher. Isolate the affinity of this process and let the operating system take care of the other processes. You can use the *psutil* library in your application to do this. Here we are using the ```taskset -cp [core_index] [pid]``` command to stay pure Python. You can also enter more than 1 CPU Core, just enter this value as a list of integers. Ex: ```[0,1]``` and it will use the 1st and 2nd cpu core available on your machine.
+
+
+## Running the application
+
+Once the configuration file is prepared, run stressanapi by calling this file with the ```--conf``` option:
+
+```bash
+# stressanapi --conf myconf.json
+```
+
+![](https://raw.githubusercontent.com/rabuchaim/StressAnAPI/main/images/stressanapi-02.png)
+
+At this moment, a call is already being made every 0.5 seconds (which was defined in my example configuration file). To see how many requests per second are being made, press the **`ENTER`** key. To view the requests, press the **`V`** key on your keyboard. To see the response of your call, press the **`B`** key on your keyboard. Press **`V`** or **`B`** again to stop to see this information.
+
+![](https://raw.githubusercontent.com/rabuchaim/StressAnAPI/main/images/stressanapi-03.png)
+
+
+## Control Options
+
+Press the **`H`** key to view available control options.
+
+![](https://raw.githubusercontent.com/rabuchaim/StressAnAPI/main/images/stressanapi-05.png)
+
+You can decrease the interval, increase the burst and even increase the number of threads to test the limits of your API. From time to time you can press **`V`** or **`B`** to view returning calls. And press the **`ENTER`** key to see the number of requests per second that are currently being made and press the **`S`** key to access the statistics of all requests that have already been made. If necessary, you can pause the process pressing the **`P`** key.
+
+The control is very intuitive and you can even play with it.
+
+![](https://raw.githubusercontent.com/rabuchaim/StressAnAPI/main/images/stressanapi-06.png)
+
+> *The last section of the statistics, which reads "Statistics: Elapsed time", the last items 50th pct, 75th pct, 90th pct and 99th pct, mean that: 50% of requests are below 0.002436 second, and 75% of requests are below 0.002743 second, etc.* 
+
+## For the next releases:
+
+- Possibility of reading files containing URL data, or even post_data and header fields. Something like: {"X-Forwarded-For": "random:ipv4"} where it will put a different randomic IPv4 for each request, or even {"name": "filerand:names.txt"}, where it will put the content of one of the lines names.txt file in the "name" field for each request **<< ON THE WAY**
+
+- Use a CSV file with a sequence of URLs and methods to be called in sequence
+
+## Sugestions, request of new features, feedbacks, bugs...
+
+Open an [issue](https://github.com/rabuchaim/StressAnAPI/issues) or e-mail me: ricardoabuchaim at gmail.com