poorconn 0.1.1

Simulating poor network connections.

Poorconn is a Python package that simulates poor network conditions. It is suitable for testing purposes, for both Python and non-Python projects.

It is capable of simulating the following poor network conditions:

• Throttled network connections. (delay_before_sending, delay_before_sending_upon_acceptance)

• Servers that cut off connections immediately upon accepting them. (close_upon_accepting)

• Connections that are initially slow, but become normal subsequently. (delay_before_sending_once, delay_before_sending_upon_acceptance_once)

Quickstart

Install this package via

$ pip install 'poorconn[full]'  # or "pip install poorconn" if you don't need pytest support

The following example starts a local HTTP server at port 8000 that always closes connections upon accepting them:

from http.server import HTTPServer, SimpleHTTPRequestHandler
from poorconn import close_upon_accepting, make_socket_patchable

# Start a local HTTP server that always closes connections upon established
with HTTPServer(("localhost", 8000), SimpleHTTPRequestHandler) as httpd:
    httpd.socket = make_socket_patchable(httpd.socket)
    close_upon_accepting(httpd.socket)
    httpd.serve_forever()

After running the code above, connections from a client would establish but fail to communicate subsequently:

$ wget -t 1 http://127.0.0.1:8000
Connecting to 127.0.0.1:8000... connected.
HTTP request sent, awaiting response... No data received.
Giving up.

For another example, to start a local HTTP server that always throttle connections upon accepting them, simply replace close_upon_accepting(s) above with delay_before_sending_upon_acceptance(s, t=1, length=1024) and adjust imports (here, poorconn.delay_before_sending_upon_acceptance delays roughly 1 seconds for every 1024 bytes sent):

$ wget http://127.0.0.1:8000
Connecting to 127.0.0.1:8000... connected.
HTTP request sent, awaiting response... 200 OK
Length: 1609 (1.6K) [text/html]
Saving to: 'index.html'

index.html    1.57K   804 B/s    in 2.0s  <====== NOTE the time

'index.html' saved [1609/1609]

(Output above is abridged.)

See the poorconn module API references for a list of such simulation functions.

Integration with Pytest

If you use pytest, you can also take advantage of poorconn fixtures in poorconn.pytest_plugin. The following example gets you started with testing against a slow HTTP server:

pytest_plugins = ('poorconn',)

from pathlib import Path
import time
import requests
import pytest

@pytest.mark.poorconn_http_server_config(t=2, length=1024)
def test_slow_http_server(poorconn_http_server, tmp_path):
    "Test GETing from a slow local http server that delays 2 seconds to send every 1024 bytes."
    (tmp_path / 'index.txt').write_bytes(b'h' * 1024)
    starting_time = time.time()
    # Replace the following line with the program you want to test
    content = requests.get(f'{poorconn_http_server.url}/index.txt').content
    ending_time = time.time()
    assert ending_time - starting_time > 2

Bug Reports and Feature Requests

Please open a ticket on the GitLab Issue Tracker.

Contributing

Contributions are welcome! To get started, check out CONTRIBUTING.

Copyright and License

Copyright (C) 2020–2021 Hong Xu <[e-mail]>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.