httpperf 1.0rc1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- httpperf-1.0rc1/LICENSE +21 -0
- httpperf-1.0rc1/MANIFEST.in +1 -0
- httpperf-1.0rc1/NOTICE +118 -0
- httpperf-1.0rc1/PKG-INFO +256 -0
- httpperf-1.0rc1/README.md +230 -0
- httpperf-1.0rc1/httpperf/__init__.py +865 -0
- httpperf-1.0rc1/httpperf/version.py +1 -0
- httpperf-1.0rc1/httpperf.egg-info/PKG-INFO +256 -0
- httpperf-1.0rc1/httpperf.egg-info/SOURCES.txt +32 -0
- httpperf-1.0rc1/httpperf.egg-info/dependency_links.txt +1 -0
- httpperf-1.0rc1/httpperf.egg-info/top_level.txt +1 -0
- httpperf-1.0rc1/pyproject.toml +72 -0
- httpperf-1.0rc1/setup.cfg +4 -0
- httpperf-1.0rc1/setup.py +29 -0
- httpperf-1.0rc1/src/ae/.clang-format +2 -0
- httpperf-1.0rc1/src/ae/ae.c +494 -0
- httpperf-1.0rc1/src/ae/ae.h +126 -0
- httpperf-1.0rc1/src/ae/ae_epoll.c +135 -0
- httpperf-1.0rc1/src/ae/ae_evport.c +320 -0
- httpperf-1.0rc1/src/ae/ae_kqueue.c +138 -0
- httpperf-1.0rc1/src/ae/ae_select.c +106 -0
- httpperf-1.0rc1/src/ae/atomicvar.h +94 -0
- httpperf-1.0rc1/src/ae/config.h +17 -0
- httpperf-1.0rc1/src/ae/zmalloc.c +429 -0
- httpperf-1.0rc1/src/ae/zmalloc.h +99 -0
- httpperf-1.0rc1/src/httpperf.c +1754 -0
- httpperf-1.0rc1/tests/test_connections.py +278 -0
- httpperf-1.0rc1/tests/test_cookie.py +14 -0
- httpperf-1.0rc1/tests/test_engine.py +286 -0
- httpperf-1.0rc1/tests/test_http_versions.py +127 -0
- httpperf-1.0rc1/tests/test_httpbin.py +288 -0
- httpperf-1.0rc1/tests/test_leaks.py +41 -0
- httpperf-1.0rc1/tests/test_response.py +75 -0
- httpperf-1.0rc1/tests/test_tls.py +152 -0
httpperf-1.0rc1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2017-2026 Tony Simpson
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
graft src
|
httpperf-1.0rc1/NOTICE
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
httpperf
|
|
2
|
+
Copyright (c) 2017-2026 Tony Simpson
|
|
3
|
+
|
|
4
|
+
httpperf is licensed under the MIT License (see LICENSE). It includes, or in
|
|
5
|
+
its binary wheels bundles, the third-party software below.
|
|
6
|
+
|
|
7
|
+
=========================================================================
|
|
8
|
+
== Redis Event Library Notice ==
|
|
9
|
+
=========================================================================
|
|
10
|
+
|
|
11
|
+
src/ae is the event library from the redis project, as used by wrk, with
|
|
12
|
+
small changes.
|
|
13
|
+
|
|
14
|
+
This product includes software developed by Salvatore Sanfilippo and
|
|
15
|
+
other contributors to the redis project.
|
|
16
|
+
|
|
17
|
+
Copyright (c) 2006-2010, Salvatore Sanfilippo <antirez at gmail dot com>
|
|
18
|
+
Copyright (c) 2006-2012, Salvatore Sanfilippo <antirez at gmail dot com>
|
|
19
|
+
Copyright (c) 2009-2010, Salvatore Sanfilippo <antirez at gmail dot com>
|
|
20
|
+
Copyright (c) 2009-2012, Salvatore Sanfilippo <antirez at gmail dot com>
|
|
21
|
+
Copyright (c) 2015, Salvatore Sanfilippo <antirez at gmail dot com>
|
|
22
|
+
Copyright (C) 2009 Harish Mallipeddi - harish.mallipeddi@gmail.com
|
|
23
|
+
Copyright (c) 2012, Joyent, Inc. All rights reserved.
|
|
24
|
+
|
|
25
|
+
Redistribution and use in source and binary forms, with or without
|
|
26
|
+
modification, are permitted provided that the following conditions are
|
|
27
|
+
met:
|
|
28
|
+
|
|
29
|
+
* Redistributions of source code must retain the above copyright
|
|
30
|
+
notice, this list of conditions and the following disclaimer.
|
|
31
|
+
|
|
32
|
+
* Redistributions in binary form must reproduce the above copyright
|
|
33
|
+
notice, this list of conditions and the following disclaimer in the
|
|
34
|
+
documentation and/or other materials provided with the
|
|
35
|
+
distribution.
|
|
36
|
+
|
|
37
|
+
* Neither the name of Redis nor the names of its contributors may be
|
|
38
|
+
used to endorse or promote products derived from this software
|
|
39
|
+
without specific prior written permission.
|
|
40
|
+
|
|
41
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
|
42
|
+
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
|
|
43
|
+
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
44
|
+
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
|
|
45
|
+
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
46
|
+
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
47
|
+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
48
|
+
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
49
|
+
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
50
|
+
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
51
|
+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
52
|
+
|
|
53
|
+
=========================================================================
|
|
54
|
+
== curl Notice (bundled in binary wheels) ==
|
|
55
|
+
=========================================================================
|
|
56
|
+
|
|
57
|
+
COPYRIGHT AND PERMISSION NOTICE
|
|
58
|
+
|
|
59
|
+
Copyright (c) 1996 - 2026, Daniel Stenberg, <daniel@haxx.se>, and many
|
|
60
|
+
contributors, see the THANKS file.
|
|
61
|
+
|
|
62
|
+
All rights reserved.
|
|
63
|
+
|
|
64
|
+
Permission to use, copy, modify, and distribute this software for any purpose
|
|
65
|
+
with or without fee is hereby granted, provided that the above copyright
|
|
66
|
+
notice and this permission notice appear in all copies.
|
|
67
|
+
|
|
68
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
69
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
70
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN
|
|
71
|
+
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
|
72
|
+
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
|
73
|
+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
|
|
74
|
+
OR OTHER DEALINGS IN THE SOFTWARE.
|
|
75
|
+
|
|
76
|
+
Except as contained in this notice, the name of a copyright holder shall not
|
|
77
|
+
be used in advertising or otherwise to promote the sale, use or other dealings
|
|
78
|
+
in this Software without prior written authorization of the copyright holder.
|
|
79
|
+
|
|
80
|
+
=========================================================================
|
|
81
|
+
== nghttp2 Notice (bundled in binary wheels) ==
|
|
82
|
+
=========================================================================
|
|
83
|
+
|
|
84
|
+
The MIT License
|
|
85
|
+
|
|
86
|
+
Copyright (c) 2012, 2014, 2015, 2016 Tatsuhiro Tsujikawa
|
|
87
|
+
Copyright (c) 2012, 2014, 2015, 2016 nghttp2 contributors
|
|
88
|
+
|
|
89
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
|
90
|
+
a copy of this software and associated documentation files (the
|
|
91
|
+
"Software"), to deal in the Software without restriction, including
|
|
92
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
|
93
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
|
94
|
+
permit persons to whom the Software is furnished to do so, subject to
|
|
95
|
+
the following conditions:
|
|
96
|
+
|
|
97
|
+
The above copyright notice and this permission notice shall be
|
|
98
|
+
included in all copies or substantial portions of the Software.
|
|
99
|
+
|
|
100
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
101
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
102
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
103
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
104
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
105
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
106
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
107
|
+
|
|
108
|
+
=========================================================================
|
|
109
|
+
== OpenSSL Notice (bundled in binary wheels) ==
|
|
110
|
+
=========================================================================
|
|
111
|
+
|
|
112
|
+
This product includes software developed by the OpenSSL Project for use
|
|
113
|
+
in the OpenSSL Toolkit (https://www.openssl.org/).
|
|
114
|
+
|
|
115
|
+
Copyright (c) 1998-2026 The OpenSSL Project Authors.
|
|
116
|
+
|
|
117
|
+
OpenSSL is licensed under the Apache License, Version 2.0. You may obtain
|
|
118
|
+
a copy of the License at https://www.apache.org/licenses/LICENSE-2.0
|
httpperf-1.0rc1/PKG-INFO
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: httpperf
|
|
3
|
+
Version: 1.0rc1
|
|
4
|
+
Summary: An asyncio HTTP client for load testing, built on libcurl.
|
|
5
|
+
Author-email: Tony Simpson <agjasimpson@gmail.com>
|
|
6
|
+
Project-URL: Source, https://github.com/tonysimpson/httpperf
|
|
7
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
8
|
+
Classifier: Intended Audience :: Developers
|
|
9
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
10
|
+
Classifier: Programming Language :: C
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
20
|
+
Classifier: Topic :: Software Development :: Testing :: Traffic Generation
|
|
21
|
+
Requires-Python: >=3.8
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
License-File: NOTICE
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# httpperf
|
|
28
|
+
|
|
29
|
+
An asyncio HTTP client for load testing, built on libcurl.
|
|
30
|
+
|
|
31
|
+
httpperf was called acurl until version 1.0.
|
|
32
|
+
|
|
33
|
+
## Design
|
|
34
|
+
|
|
35
|
+
A load-testing client has three jobs: drive as much load as possible from each machine, report the server's response times rather than time spent waiting on the client, and read responses promptly so the server never sees a slow reader. httpperf is built around these.
|
|
36
|
+
|
|
37
|
+
All network I/O runs in a small C event loop (the vendored `ae` reactor from Redis) on its own thread, which never takes the GIL. Python hands requests to that thread and collects finished responses through pipes:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
asyncio loop ──req_in pipe──▶ curl thread (ae + curl multi) ──▶ sockets
|
|
41
|
+
▲ │
|
|
42
|
+
└──────── req_out pipe ◀────────┘
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Bytes are read off the wire as they arrive, whatever Python is doing. If Python falls behind, finished responses wait in the pipe rather than in socket buffers, so the client simply sends new requests more slowly, and curl's timings stay accurate. The cost is the hand-off itself, and the curl thread uses roughly one extra core under load. That is deliberate: a spare core is cheap, and response times you can't trust are worthless.
|
|
46
|
+
|
|
47
|
+
`Response.client_lag` shows how far Python is behind (see [Timings](#timings)).
|
|
48
|
+
|
|
49
|
+
## Install
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
pip install httpperf
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Wheels are published for Linux on x86_64 and aarch64, for Python 3.9 to 3.15, with glibc 2.34 or later (Ubuntu 22.04, Debian 12, RHEL 9 and later) or musl (Alpine). They include their own libcurl, with HTTP/2 but not HTTP/3.
|
|
56
|
+
|
|
57
|
+
Anywhere else, including Python 3.8, pip builds from source against the system's libcurl, which needs its development headers and a C compiler. That libcurl decides whether HTTP/3 is available.
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
sudo apt install libcurl4-openssl-dev # Debian/Ubuntu
|
|
61
|
+
pip install httpperf
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Quick start
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
import asyncio
|
|
68
|
+
|
|
69
|
+
import httpperf
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
async def main():
|
|
73
|
+
async with httpperf.Session() as session:
|
|
74
|
+
r = await session.get("https://example.com/")
|
|
75
|
+
print(r.status_code, r.http_version, r.total_time, r.client_lag)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
asyncio.run(main())
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Sessions are cheap: create one per virtual user or journey. They share a default `Engine` (the curl thread, the shared connection pool and the TLS cache) unless you pass your own.
|
|
82
|
+
|
|
83
|
+
## API
|
|
84
|
+
|
|
85
|
+
### `Session(*, engine=None, ...)`
|
|
86
|
+
|
|
87
|
+
All arguments are keyword-only. A session can be created anywhere, even outside a running asyncio loop.
|
|
88
|
+
|
|
89
|
+
| Argument | Default | Meaning |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| `engine` | `None` | The `Engine` to use. `None` means the default engine of the asyncio loop the session is first used in, created when first needed and shared by every session in that loop without one. |
|
|
92
|
+
| `connections` | `"shared"` | `"shared"`: the engine's pool. `"session"`: the session's own pool. `"none"`: a new connection for every request. |
|
|
93
|
+
| `tls` | `"shared"` | Where TLS session tickets are kept. `"shared"`: in the engine, so new connections resume their handshake. `"session"`: per session, so each session starts with a full handshake. |
|
|
94
|
+
| `http_version` | `"HTTP/2"` | `"HTTP/2"`: HTTP/2 over TLS when the server offers it, with requests waiting to share one multiplexed connection. Plain http uses HTTP/1.1. `"HTTP/1.1"`: HTTP/1.1 only. `"HTTP/3"`: HTTP/3 over QUIC only, with no fallback, so requests fail if the server does not offer it. |
|
|
95
|
+
| `idle_timeout` | `118` | Seconds a connection may sit idle and still be reused. |
|
|
96
|
+
| `max_connection_age` | `0` | Seconds after which a connection is no longer reused, however busy it is. 0 means no limit. |
|
|
97
|
+
| `max_host_connections` | `0` | Per-session cap on connections per host. Needs `connections="session"` or `"none"`. |
|
|
98
|
+
| `max_connections` | `0` | Per-session cap on connections in use. Needs `connections="session"` or `"none"`. |
|
|
99
|
+
| `cert` | `None` | `(certfile, keyfile)` paths for a client certificate, used by every request unless the request overrides it. |
|
|
100
|
+
| `timeout` | `None` | Seconds allowed for each request, from the start of the transfer to the last byte (each redirect hop separately). `None` or 0 means no limit. |
|
|
101
|
+
| `connect_timeout` | `None` | Seconds allowed to connect, TLS included. `None` means curl's default of 300 s. |
|
|
102
|
+
| `verify` | `False` | Server certificate checking. `False`: none, as most load tests want. `True`: check against the system CA bundle: `SSL_CERT_FILE` if set, otherwise libcurl's own default, or the usual system locations if it has none. A path: check against that CA bundle. Requests can override it. |
|
|
103
|
+
| `json_dumps` | `None` | Function that turns a `json=` argument into the request body (`str` or `bytes`). `None` means the engine's. |
|
|
104
|
+
| `json_loads` | `None` | Function that turns the response body (`bytes`) into the result of `json()`. `None` means the engine's. |
|
|
105
|
+
|
|
106
|
+
Proxies come from the environment, as curl reads them: `http_proxy` (not `HTTP_PROXY`, which curl ignores for security), `https_proxy` or `HTTPS_PROXY`, then `all_proxy` or `ALL_PROXY`, with `no_proxy` or `NO_PROXY` for exceptions. A session reads them once, when it is created, so later changes apply to new sessions only.
|
|
107
|
+
|
|
108
|
+
Cookies always belong to the session, whatever the connection settings.
|
|
109
|
+
|
|
110
|
+
### `Engine(*, max_host_connections=0, max_total_connections=0, max_idle_connections=1000, json_dumps=..., json_loads=...)`
|
|
111
|
+
|
|
112
|
+
What sessions share: the curl thread, the shared connection pool, the TLS session cache and the limits. Most programs never create one. Create one to set limits, or to keep groups of sessions in separate pools, and pass it to `Session(engine=...)`.
|
|
113
|
+
|
|
114
|
+
| Argument | Meaning |
|
|
115
|
+
|---|---|
|
|
116
|
+
| `max_host_connections` | Cap on connections per host for the engine's sessions that use the shared pool or no pool. 0 means no limit. httpperf queues requests above it and reports the wait as `queue_time`. |
|
|
117
|
+
| `max_total_connections` | Cap on all connections for the same sessions. 0 means no limit. |
|
|
118
|
+
| `max_idle_connections` | How many connections each pool keeps (the shared pool, and each session's own pool). Must be at least 1. |
|
|
119
|
+
| `json_dumps`, `json_loads` | The JSON functions for the engine's sessions, unless a session sets its own. The defaults use the standard library: compact output, and bodies decoded as UTF-8. See [JSON](#json). |
|
|
120
|
+
|
|
121
|
+
Each asyncio loop has its own default engine, so sessions without an engine work in any thread, and in each `asyncio.run()`, without setup. A loop's default engine lasts as long as the loop, and is closed once the loop has been closed and no session uses it.
|
|
122
|
+
|
|
123
|
+
An engine binds to the asyncio loop running when it is first used, and so does a session. An engine serves one loop at a time, and using it from a second live loop raises `RuntimeError`. Once its loop is closed, as at the end of `asyncio.run()`, it binds to the next one and keeps its pool. So a session kept between `asyncio.run()` calls keeps its connections. To run loops in several threads at once with your own engines, give each thread its own `Engine`.
|
|
124
|
+
|
|
125
|
+
`engine.close()` stops the curl thread and closes the shared pool's connections, and later requests raise `RuntimeError`. Requests still in flight fail with `RequestError`, and a `ResourceWarning` says how many there were. `with` and `async with` call `close()` on exit. An engine that is no longer referenced is closed automatically. See [docs/connections.md](docs/connections.md) for how these fit together.
|
|
126
|
+
|
|
127
|
+
### Session methods
|
|
128
|
+
|
|
129
|
+
- `await session.get(url, **kwargs)`, and likewise `post`, `put`, `patch`, `delete`, `head` and `options`.
|
|
130
|
+
- `await session.request(method, url, **kwargs)`.
|
|
131
|
+
- `session.close()`: closes the session's connections once its requests finish. Later requests raise `RuntimeError`. `with` and `async with` call it on exit.
|
|
132
|
+
- `session.cookies()`: the cookie jar as a dict.
|
|
133
|
+
- `session.get_cookie_list()`, `session.add_cookie_list(cookies)`, `session.erase_all_cookies()` and `session.erase_session_cookies()`: work with `Cookie` objects. These are ordinary methods, not coroutines.
|
|
134
|
+
- `session.set_response_callback(callback)`: called with each `Response`, including each hop of a redirect.
|
|
135
|
+
|
|
136
|
+
### Request arguments
|
|
137
|
+
|
|
138
|
+
| Argument | Meaning |
|
|
139
|
+
|---|---|
|
|
140
|
+
| `params` | Query parameters: a dict or list of pairs (lists as values repeat the key), or a ready-made string. Added to any query already in the URL. |
|
|
141
|
+
| `headers` | Dict of headers. |
|
|
142
|
+
| `headers_list` | List of `"Name: value"` strings, for repeated headers. |
|
|
143
|
+
| `cookies` | Dict of cookies to send with this request (added to the session jar). |
|
|
144
|
+
| `cookie_list` | List of `Cookie` objects. |
|
|
145
|
+
| `auth` | `(username, password)` for basic auth. |
|
|
146
|
+
| `data` | Request body: `str` or `bytes` as is, or a dict or list of pairs, form-encoded with `Content-Type: application/x-www-form-urlencoded` unless you set it. |
|
|
147
|
+
| `json` | Object to send as JSON, encoded with the session's `json_dumps`. Sets `Content-Type: application/json` unless you set it. |
|
|
148
|
+
| `files` | Dict (or list of pairs) of files to send as `multipart/form-data`, with any `data` dict as extra fields. A value is an open file, or `(filename, content)` or `(filename, content, content_type)`, where content is `bytes`, `str` or a file. Files are read into memory. |
|
|
149
|
+
| `cert` | `(certfile, keyfile)`, overriding the session's certificate. |
|
|
150
|
+
| `verify` | `True`, `False` or a CA bundle path, overriding the session's `verify`. |
|
|
151
|
+
| `timeout`, `connect_timeout` | Override the session's. `timeout=0` removes the session's limit for this request. |
|
|
152
|
+
| `allow_redirects` | Follow redirects (default `True`; `False` for `head`). |
|
|
153
|
+
| `max_redirects` | Default 5. Raises `RequestError("Max Redirects")` beyond it. |
|
|
154
|
+
|
|
155
|
+
Failed transfers raise `httpperf.RequestError` with curl's detailed error message, such as `Failed to connect to 127.0.0.1 port 8080 after 0 ms: Couldn't connect to server`. Its `code` is curl's error code. Timeouts raise `httpperf.Timeout`, a subclass, so they can be counted separately.
|
|
156
|
+
|
|
157
|
+
### Response
|
|
158
|
+
|
|
159
|
+
| Attribute | Meaning |
|
|
160
|
+
|---|---|
|
|
161
|
+
| `status_code` | HTTP status. |
|
|
162
|
+
| `ok` | `True` if the status is below 400. |
|
|
163
|
+
| `reason` | Reason phrase from the status line, or the standard phrase for HTTP/2 and HTTP/3, which send none. |
|
|
164
|
+
| `raise_for_status()` | Raises `httpperf.HTTPError` (a `RequestError`, with the `response`) for 4xx and 5xx statuses. |
|
|
165
|
+
| `elapsed` | `total_time` as a `timedelta`. |
|
|
166
|
+
| `url` | Effective URL. |
|
|
167
|
+
| `redirect_url` | Location of a redirect, or `None`. |
|
|
168
|
+
| `history` | Earlier responses in a redirect chain. |
|
|
169
|
+
| `http_version` | `"HTTP/1.0"`, `"HTTP/1.1"`, `"HTTP/2"` or `"HTTP/3"`. |
|
|
170
|
+
| `headers` | Case-insensitive mapping of the response headers. Repeated headers are joined with `, `, as in requests. `headers_tuple` keeps repeats and order. Both skip interim responses such as `100 Continue`. `header` is the raw text of every header block, decoded as latin-1. |
|
|
171
|
+
| `body` | Bytes. |
|
|
172
|
+
| `text` | Body decoded with `encoding`. |
|
|
173
|
+
| `encoding` | From the `Content-Type` charset, else latin-1 (`utf-8` for JSON). Can be set. |
|
|
174
|
+
| `json()` | Body parsed with the session's `json_loads`, once. By default the standard library, always as UTF-8, as RFC 8259 requires. |
|
|
175
|
+
| `cookies`, `cookielist` | The session's cookie jar at the time you read it (not only the cookies this response set). Empty once the session is closed. |
|
|
176
|
+
| `primary_ip` | Address connected to. |
|
|
177
|
+
| `upload_size`, `download_size` | Bytes, as integers. |
|
|
178
|
+
| `request` | The `Request`: `method`, `url`, `headers`, `cookies`, `auth`, `data`. |
|
|
179
|
+
|
|
180
|
+
### JSON
|
|
181
|
+
|
|
182
|
+
By default httpperf uses the standard library's `json`: compact output for `json=`, and response bodies decoded as UTF-8 for `json()`. It needs no extra dependency and has the most scrutinised parser, which matters because load tests often fetch responses from third parties.
|
|
183
|
+
|
|
184
|
+
If JSON costs too much CPU, pass faster functions as `json_dumps` and `json_loads`, on the `Engine` for all its sessions or on one `Session`. [orjson](https://github.com/ijl/orjson) is a good choice for encoding, and [pysimdjson](https://github.com/TkTech/pysimdjson) for decoding. Create the parser once, at module scope, since it keeps its buffers between documents:
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
import httpperf
|
|
188
|
+
import orjson
|
|
189
|
+
import simdjson
|
|
190
|
+
|
|
191
|
+
parser = simdjson.Parser()
|
|
192
|
+
engine = httpperf.Engine(json_dumps=orjson.dumps, json_loads=parser.parse)
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
async def journey():
|
|
196
|
+
async with httpperf.Session(engine=engine) as session:
|
|
197
|
+
r = await session.post("https://example.com/search", json={"q": "httpperf"})
|
|
198
|
+
return r.json()["items"][3]["name"]
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Things to know:
|
|
202
|
+
|
|
203
|
+
- orjson is about 8 times faster than `json` on larger payloads, but turns `NaN` into `null` and refuses integers over 64 bits.
|
|
204
|
+
- `parser.parse` is lazy: only the values you touch become Python objects. That was about 8 times faster than `json.loads` for reading one field of a 500 KB document. The result is read-only and not a real `dict` or `list`; `.as_dict()` and `.as_list()` convert it. Documents stay valid after the parser moves on to the next one.
|
|
205
|
+
- To get real `dict`s and `list`s from simdjson, use `json_loads=lambda body: parser.parse(body, True)`.
|
|
206
|
+
- Request bodies that never change can be encoded once and sent as `data=`, with `headers={"Content-Type": "application/json"}`.
|
|
207
|
+
|
|
208
|
+
## Timings
|
|
209
|
+
|
|
210
|
+
All in seconds.
|
|
211
|
+
|
|
212
|
+
| Attribute | Meaning |
|
|
213
|
+
|---|---|
|
|
214
|
+
| `start_time`, `end_time` | Wall-clock times (`time.time()`) when the request was made and when Python received the response. |
|
|
215
|
+
| `namelookup_time` | DNS, measured by curl from the start of the transfer. |
|
|
216
|
+
| `connect_time` | TCP connect complete. 0 when the connection was reused. |
|
|
217
|
+
| `appconnect_time` | TLS handshake complete. 0 for plain http and reused connections. |
|
|
218
|
+
| `pretransfer_time` | Ready to send. |
|
|
219
|
+
| `posttransfer_time` | Request fully sent. `starttransfer_time − posttransfer_time` is the server's time to first byte, without connection setup or upload. `None` with libcurl older than 8.10. |
|
|
220
|
+
| `starttransfer_time` | First byte received. |
|
|
221
|
+
| `total_time` | Transfer complete. |
|
|
222
|
+
| `queue_time` | Time waiting in httpperf's queue for a connection, under the engine or session limits. 0 if the request did not wait. curl's timings start after it. |
|
|
223
|
+
| `client_lag` | `end_time − start_time − total_time − queue_time`: time the request spent waiting on Python, before it was sent and after it finished. Measured with the monotonic clock, so clock changes don't affect it. |
|
|
224
|
+
|
|
225
|
+
curl measures its timings on the curl thread, so a busy Python process does not inflate them. `client_lag` is how you see that Python is the bottleneck: if it grows, the client cannot keep up, and achieved request rates describe the client rather than the server. Report it alongside response times (p50, p99, max).
|
|
226
|
+
|
|
227
|
+
`queue_time` is real waiting that a user would see (a browser's "stalled" time), but it is client-side, so keep it out of server latency.
|
|
228
|
+
|
|
229
|
+
## Known limitations
|
|
230
|
+
|
|
231
|
+
- curl closes expired idle connections lazily, the next time the pool needs a connection, so the server sees the close late. See [docs/connections.md](docs/connections.md).
|
|
232
|
+
- Requests in flight when `Engine.close()` is called never complete.
|
|
233
|
+
|
|
234
|
+
## Development
|
|
235
|
+
|
|
236
|
+
```sh
|
|
237
|
+
make test
|
|
238
|
+
make lint # ruff and clang-format, check only
|
|
239
|
+
make lint-fix # apply formatting and fixes
|
|
240
|
+
make clean # remove build output, caches and profiler output (keeps .venv)
|
|
241
|
+
make distclean # also remove .venv
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Each target first creates `.venv` with uv, if needed, and installs httpperf in editable mode with the dev tools. It reinstalls when `setup.py`, `pyproject.toml` or the C sources change, so C edits are rebuilt automatically. `make venv` does only that step.
|
|
245
|
+
|
|
246
|
+
`make venv PY_VERSION=3.8 VENV=.venv-3.8` builds another venv, and `VENV=.venv-3.8` on `make test` or `make lint` uses it.
|
|
247
|
+
|
|
248
|
+
To release, set `__version__` in `httpperf/version.py` (for example `1.0rc1` or `1.0`), commit and push to main, then run `make release`. It tags `v<version>` and pushes the tag, and the release workflow builds the wheels and publishes them to PyPI.
|
|
249
|
+
|
|
250
|
+
The tests run local servers: pytest-httpbin, small threaded `http.server` servers for connection counting and TLS, and hypercorn for HTTP/2 and HTTP/3 (skipped on Python 3.8, where hypercorn's HTTP/3 server hangs on shutdown). Client certificates are generated with `openssl`. The httpbin server is single-threaded, so keep concurrency in tests low.
|
|
251
|
+
|
|
252
|
+
Set `HTTPPERF_PROFILE=1` when building to instrument the extension. See [docs/profiling.md](docs/profiling.md).
|
|
253
|
+
|
|
254
|
+
## Licence
|
|
255
|
+
|
|
256
|
+
MIT. See [LICENSE](LICENSE). [NOTICE](NOTICE) covers the bundled Redis event library and the libraries included in the binary wheels.
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# httpperf
|
|
2
|
+
|
|
3
|
+
An asyncio HTTP client for load testing, built on libcurl.
|
|
4
|
+
|
|
5
|
+
httpperf was called acurl until version 1.0.
|
|
6
|
+
|
|
7
|
+
## Design
|
|
8
|
+
|
|
9
|
+
A load-testing client has three jobs: drive as much load as possible from each machine, report the server's response times rather than time spent waiting on the client, and read responses promptly so the server never sees a slow reader. httpperf is built around these.
|
|
10
|
+
|
|
11
|
+
All network I/O runs in a small C event loop (the vendored `ae` reactor from Redis) on its own thread, which never takes the GIL. Python hands requests to that thread and collects finished responses through pipes:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
asyncio loop ──req_in pipe──▶ curl thread (ae + curl multi) ──▶ sockets
|
|
15
|
+
▲ │
|
|
16
|
+
└──────── req_out pipe ◀────────┘
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Bytes are read off the wire as they arrive, whatever Python is doing. If Python falls behind, finished responses wait in the pipe rather than in socket buffers, so the client simply sends new requests more slowly, and curl's timings stay accurate. The cost is the hand-off itself, and the curl thread uses roughly one extra core under load. That is deliberate: a spare core is cheap, and response times you can't trust are worthless.
|
|
20
|
+
|
|
21
|
+
`Response.client_lag` shows how far Python is behind (see [Timings](#timings)).
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
pip install httpperf
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Wheels are published for Linux on x86_64 and aarch64, for Python 3.9 to 3.15, with glibc 2.34 or later (Ubuntu 22.04, Debian 12, RHEL 9 and later) or musl (Alpine). They include their own libcurl, with HTTP/2 but not HTTP/3.
|
|
30
|
+
|
|
31
|
+
Anywhere else, including Python 3.8, pip builds from source against the system's libcurl, which needs its development headers and a C compiler. That libcurl decides whether HTTP/3 is available.
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
sudo apt install libcurl4-openssl-dev # Debian/Ubuntu
|
|
35
|
+
pip install httpperf
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Quick start
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import asyncio
|
|
42
|
+
|
|
43
|
+
import httpperf
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
async def main():
|
|
47
|
+
async with httpperf.Session() as session:
|
|
48
|
+
r = await session.get("https://example.com/")
|
|
49
|
+
print(r.status_code, r.http_version, r.total_time, r.client_lag)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
asyncio.run(main())
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Sessions are cheap: create one per virtual user or journey. They share a default `Engine` (the curl thread, the shared connection pool and the TLS cache) unless you pass your own.
|
|
56
|
+
|
|
57
|
+
## API
|
|
58
|
+
|
|
59
|
+
### `Session(*, engine=None, ...)`
|
|
60
|
+
|
|
61
|
+
All arguments are keyword-only. A session can be created anywhere, even outside a running asyncio loop.
|
|
62
|
+
|
|
63
|
+
| Argument | Default | Meaning |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| `engine` | `None` | The `Engine` to use. `None` means the default engine of the asyncio loop the session is first used in, created when first needed and shared by every session in that loop without one. |
|
|
66
|
+
| `connections` | `"shared"` | `"shared"`: the engine's pool. `"session"`: the session's own pool. `"none"`: a new connection for every request. |
|
|
67
|
+
| `tls` | `"shared"` | Where TLS session tickets are kept. `"shared"`: in the engine, so new connections resume their handshake. `"session"`: per session, so each session starts with a full handshake. |
|
|
68
|
+
| `http_version` | `"HTTP/2"` | `"HTTP/2"`: HTTP/2 over TLS when the server offers it, with requests waiting to share one multiplexed connection. Plain http uses HTTP/1.1. `"HTTP/1.1"`: HTTP/1.1 only. `"HTTP/3"`: HTTP/3 over QUIC only, with no fallback, so requests fail if the server does not offer it. |
|
|
69
|
+
| `idle_timeout` | `118` | Seconds a connection may sit idle and still be reused. |
|
|
70
|
+
| `max_connection_age` | `0` | Seconds after which a connection is no longer reused, however busy it is. 0 means no limit. |
|
|
71
|
+
| `max_host_connections` | `0` | Per-session cap on connections per host. Needs `connections="session"` or `"none"`. |
|
|
72
|
+
| `max_connections` | `0` | Per-session cap on connections in use. Needs `connections="session"` or `"none"`. |
|
|
73
|
+
| `cert` | `None` | `(certfile, keyfile)` paths for a client certificate, used by every request unless the request overrides it. |
|
|
74
|
+
| `timeout` | `None` | Seconds allowed for each request, from the start of the transfer to the last byte (each redirect hop separately). `None` or 0 means no limit. |
|
|
75
|
+
| `connect_timeout` | `None` | Seconds allowed to connect, TLS included. `None` means curl's default of 300 s. |
|
|
76
|
+
| `verify` | `False` | Server certificate checking. `False`: none, as most load tests want. `True`: check against the system CA bundle: `SSL_CERT_FILE` if set, otherwise libcurl's own default, or the usual system locations if it has none. A path: check against that CA bundle. Requests can override it. |
|
|
77
|
+
| `json_dumps` | `None` | Function that turns a `json=` argument into the request body (`str` or `bytes`). `None` means the engine's. |
|
|
78
|
+
| `json_loads` | `None` | Function that turns the response body (`bytes`) into the result of `json()`. `None` means the engine's. |
|
|
79
|
+
|
|
80
|
+
Proxies come from the environment, as curl reads them: `http_proxy` (not `HTTP_PROXY`, which curl ignores for security), `https_proxy` or `HTTPS_PROXY`, then `all_proxy` or `ALL_PROXY`, with `no_proxy` or `NO_PROXY` for exceptions. A session reads them once, when it is created, so later changes apply to new sessions only.
|
|
81
|
+
|
|
82
|
+
Cookies always belong to the session, whatever the connection settings.
|
|
83
|
+
|
|
84
|
+
### `Engine(*, max_host_connections=0, max_total_connections=0, max_idle_connections=1000, json_dumps=..., json_loads=...)`
|
|
85
|
+
|
|
86
|
+
What sessions share: the curl thread, the shared connection pool, the TLS session cache and the limits. Most programs never create one. Create one to set limits, or to keep groups of sessions in separate pools, and pass it to `Session(engine=...)`.
|
|
87
|
+
|
|
88
|
+
| Argument | Meaning |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `max_host_connections` | Cap on connections per host for the engine's sessions that use the shared pool or no pool. 0 means no limit. httpperf queues requests above it and reports the wait as `queue_time`. |
|
|
91
|
+
| `max_total_connections` | Cap on all connections for the same sessions. 0 means no limit. |
|
|
92
|
+
| `max_idle_connections` | How many connections each pool keeps (the shared pool, and each session's own pool). Must be at least 1. |
|
|
93
|
+
| `json_dumps`, `json_loads` | The JSON functions for the engine's sessions, unless a session sets its own. The defaults use the standard library: compact output, and bodies decoded as UTF-8. See [JSON](#json). |
|
|
94
|
+
|
|
95
|
+
Each asyncio loop has its own default engine, so sessions without an engine work in any thread, and in each `asyncio.run()`, without setup. A loop's default engine lasts as long as the loop, and is closed once the loop has been closed and no session uses it.
|
|
96
|
+
|
|
97
|
+
An engine binds to the asyncio loop running when it is first used, and so does a session. An engine serves one loop at a time, and using it from a second live loop raises `RuntimeError`. Once its loop is closed, as at the end of `asyncio.run()`, it binds to the next one and keeps its pool. So a session kept between `asyncio.run()` calls keeps its connections. To run loops in several threads at once with your own engines, give each thread its own `Engine`.
|
|
98
|
+
|
|
99
|
+
`engine.close()` stops the curl thread and closes the shared pool's connections, and later requests raise `RuntimeError`. Requests still in flight fail with `RequestError`, and a `ResourceWarning` says how many there were. `with` and `async with` call `close()` on exit. An engine that is no longer referenced is closed automatically. See [docs/connections.md](docs/connections.md) for how these fit together.
|
|
100
|
+
|
|
101
|
+
### Session methods
|
|
102
|
+
|
|
103
|
+
- `await session.get(url, **kwargs)`, and likewise `post`, `put`, `patch`, `delete`, `head` and `options`.
|
|
104
|
+
- `await session.request(method, url, **kwargs)`.
|
|
105
|
+
- `session.close()`: closes the session's connections once its requests finish. Later requests raise `RuntimeError`. `with` and `async with` call it on exit.
|
|
106
|
+
- `session.cookies()`: the cookie jar as a dict.
|
|
107
|
+
- `session.get_cookie_list()`, `session.add_cookie_list(cookies)`, `session.erase_all_cookies()` and `session.erase_session_cookies()`: work with `Cookie` objects. These are ordinary methods, not coroutines.
|
|
108
|
+
- `session.set_response_callback(callback)`: called with each `Response`, including each hop of a redirect.
|
|
109
|
+
|
|
110
|
+
### Request arguments
|
|
111
|
+
|
|
112
|
+
| Argument | Meaning |
|
|
113
|
+
|---|---|
|
|
114
|
+
| `params` | Query parameters: a dict or list of pairs (lists as values repeat the key), or a ready-made string. Added to any query already in the URL. |
|
|
115
|
+
| `headers` | Dict of headers. |
|
|
116
|
+
| `headers_list` | List of `"Name: value"` strings, for repeated headers. |
|
|
117
|
+
| `cookies` | Dict of cookies to send with this request (added to the session jar). |
|
|
118
|
+
| `cookie_list` | List of `Cookie` objects. |
|
|
119
|
+
| `auth` | `(username, password)` for basic auth. |
|
|
120
|
+
| `data` | Request body: `str` or `bytes` as is, or a dict or list of pairs, form-encoded with `Content-Type: application/x-www-form-urlencoded` unless you set it. |
|
|
121
|
+
| `json` | Object to send as JSON, encoded with the session's `json_dumps`. Sets `Content-Type: application/json` unless you set it. |
|
|
122
|
+
| `files` | Dict (or list of pairs) of files to send as `multipart/form-data`, with any `data` dict as extra fields. A value is an open file, or `(filename, content)` or `(filename, content, content_type)`, where content is `bytes`, `str` or a file. Files are read into memory. |
|
|
123
|
+
| `cert` | `(certfile, keyfile)`, overriding the session's certificate. |
|
|
124
|
+
| `verify` | `True`, `False` or a CA bundle path, overriding the session's `verify`. |
|
|
125
|
+
| `timeout`, `connect_timeout` | Override the session's. `timeout=0` removes the session's limit for this request. |
|
|
126
|
+
| `allow_redirects` | Follow redirects (default `True`; `False` for `head`). |
|
|
127
|
+
| `max_redirects` | Default 5. Raises `RequestError("Max Redirects")` beyond it. |
|
|
128
|
+
|
|
129
|
+
Failed transfers raise `httpperf.RequestError` with curl's detailed error message, such as `Failed to connect to 127.0.0.1 port 8080 after 0 ms: Couldn't connect to server`. Its `code` is curl's error code. Timeouts raise `httpperf.Timeout`, a subclass, so they can be counted separately.
|
|
130
|
+
|
|
131
|
+
### Response
|
|
132
|
+
|
|
133
|
+
| Attribute | Meaning |
|
|
134
|
+
|---|---|
|
|
135
|
+
| `status_code` | HTTP status. |
|
|
136
|
+
| `ok` | `True` if the status is below 400. |
|
|
137
|
+
| `reason` | Reason phrase from the status line, or the standard phrase for HTTP/2 and HTTP/3, which send none. |
|
|
138
|
+
| `raise_for_status()` | Raises `httpperf.HTTPError` (a `RequestError`, with the `response`) for 4xx and 5xx statuses. |
|
|
139
|
+
| `elapsed` | `total_time` as a `timedelta`. |
|
|
140
|
+
| `url` | Effective URL. |
|
|
141
|
+
| `redirect_url` | Location of a redirect, or `None`. |
|
|
142
|
+
| `history` | Earlier responses in a redirect chain. |
|
|
143
|
+
| `http_version` | `"HTTP/1.0"`, `"HTTP/1.1"`, `"HTTP/2"` or `"HTTP/3"`. |
|
|
144
|
+
| `headers` | Case-insensitive mapping of the response headers. Repeated headers are joined with `, `, as in requests. `headers_tuple` keeps repeats and order. Both skip interim responses such as `100 Continue`. `header` is the raw text of every header block, decoded as latin-1. |
|
|
145
|
+
| `body` | Bytes. |
|
|
146
|
+
| `text` | Body decoded with `encoding`. |
|
|
147
|
+
| `encoding` | From the `Content-Type` charset, else latin-1 (`utf-8` for JSON). Can be set. |
|
|
148
|
+
| `json()` | Body parsed with the session's `json_loads`, once. By default the standard library, always as UTF-8, as RFC 8259 requires. |
|
|
149
|
+
| `cookies`, `cookielist` | The session's cookie jar at the time you read it (not only the cookies this response set). Empty once the session is closed. |
|
|
150
|
+
| `primary_ip` | Address connected to. |
|
|
151
|
+
| `upload_size`, `download_size` | Bytes, as integers. |
|
|
152
|
+
| `request` | The `Request`: `method`, `url`, `headers`, `cookies`, `auth`, `data`. |
|
|
153
|
+
|
|
154
|
+
### JSON
|
|
155
|
+
|
|
156
|
+
By default httpperf uses the standard library's `json`: compact output for `json=`, and response bodies decoded as UTF-8 for `json()`. It needs no extra dependency and has the most scrutinised parser, which matters because load tests often fetch responses from third parties.
|
|
157
|
+
|
|
158
|
+
If JSON costs too much CPU, pass faster functions as `json_dumps` and `json_loads`, on the `Engine` for all its sessions or on one `Session`. [orjson](https://github.com/ijl/orjson) is a good choice for encoding, and [pysimdjson](https://github.com/TkTech/pysimdjson) for decoding. Create the parser once, at module scope, since it keeps its buffers between documents:
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
import httpperf
|
|
162
|
+
import orjson
|
|
163
|
+
import simdjson
|
|
164
|
+
|
|
165
|
+
parser = simdjson.Parser()
|
|
166
|
+
engine = httpperf.Engine(json_dumps=orjson.dumps, json_loads=parser.parse)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
async def journey():
|
|
170
|
+
async with httpperf.Session(engine=engine) as session:
|
|
171
|
+
r = await session.post("https://example.com/search", json={"q": "httpperf"})
|
|
172
|
+
return r.json()["items"][3]["name"]
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Things to know:
|
|
176
|
+
|
|
177
|
+
- orjson is about 8 times faster than `json` on larger payloads, but turns `NaN` into `null` and refuses integers over 64 bits.
|
|
178
|
+
- `parser.parse` is lazy: only the values you touch become Python objects. That was about 8 times faster than `json.loads` for reading one field of a 500 KB document. The result is read-only and not a real `dict` or `list`; `.as_dict()` and `.as_list()` convert it. Documents stay valid after the parser moves on to the next one.
|
|
179
|
+
- To get real `dict`s and `list`s from simdjson, use `json_loads=lambda body: parser.parse(body, True)`.
|
|
180
|
+
- Request bodies that never change can be encoded once and sent as `data=`, with `headers={"Content-Type": "application/json"}`.
|
|
181
|
+
|
|
182
|
+
## Timings
|
|
183
|
+
|
|
184
|
+
All in seconds.
|
|
185
|
+
|
|
186
|
+
| Attribute | Meaning |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `start_time`, `end_time` | Wall-clock times (`time.time()`) when the request was made and when Python received the response. |
|
|
189
|
+
| `namelookup_time` | DNS, measured by curl from the start of the transfer. |
|
|
190
|
+
| `connect_time` | TCP connect complete. 0 when the connection was reused. |
|
|
191
|
+
| `appconnect_time` | TLS handshake complete. 0 for plain http and reused connections. |
|
|
192
|
+
| `pretransfer_time` | Ready to send. |
|
|
193
|
+
| `posttransfer_time` | Request fully sent. `starttransfer_time − posttransfer_time` is the server's time to first byte, without connection setup or upload. `None` with libcurl older than 8.10. |
|
|
194
|
+
| `starttransfer_time` | First byte received. |
|
|
195
|
+
| `total_time` | Transfer complete. |
|
|
196
|
+
| `queue_time` | Time waiting in httpperf's queue for a connection, under the engine or session limits. 0 if the request did not wait. curl's timings start after it. |
|
|
197
|
+
| `client_lag` | `end_time − start_time − total_time − queue_time`: time the request spent waiting on Python, before it was sent and after it finished. Measured with the monotonic clock, so clock changes don't affect it. |
|
|
198
|
+
|
|
199
|
+
curl measures its timings on the curl thread, so a busy Python process does not inflate them. `client_lag` is how you see that Python is the bottleneck: if it grows, the client cannot keep up, and achieved request rates describe the client rather than the server. Report it alongside response times (p50, p99, max).
|
|
200
|
+
|
|
201
|
+
`queue_time` is real waiting that a user would see (a browser's "stalled" time), but it is client-side, so keep it out of server latency.
|
|
202
|
+
|
|
203
|
+
## Known limitations
|
|
204
|
+
|
|
205
|
+
- curl closes expired idle connections lazily, the next time the pool needs a connection, so the server sees the close late. See [docs/connections.md](docs/connections.md).
|
|
206
|
+
- Requests in flight when `Engine.close()` is called never complete.
|
|
207
|
+
|
|
208
|
+
## Development
|
|
209
|
+
|
|
210
|
+
```sh
|
|
211
|
+
make test
|
|
212
|
+
make lint # ruff and clang-format, check only
|
|
213
|
+
make lint-fix # apply formatting and fixes
|
|
214
|
+
make clean # remove build output, caches and profiler output (keeps .venv)
|
|
215
|
+
make distclean # also remove .venv
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Each target first creates `.venv` with uv, if needed, and installs httpperf in editable mode with the dev tools. It reinstalls when `setup.py`, `pyproject.toml` or the C sources change, so C edits are rebuilt automatically. `make venv` does only that step.
|
|
219
|
+
|
|
220
|
+
`make venv PY_VERSION=3.8 VENV=.venv-3.8` builds another venv, and `VENV=.venv-3.8` on `make test` or `make lint` uses it.
|
|
221
|
+
|
|
222
|
+
To release, set `__version__` in `httpperf/version.py` (for example `1.0rc1` or `1.0`), commit and push to main, then run `make release`. It tags `v<version>` and pushes the tag, and the release workflow builds the wheels and publishes them to PyPI.
|
|
223
|
+
|
|
224
|
+
The tests run local servers: pytest-httpbin, small threaded `http.server` servers for connection counting and TLS, and hypercorn for HTTP/2 and HTTP/3 (skipped on Python 3.8, where hypercorn's HTTP/3 server hangs on shutdown). Client certificates are generated with `openssl`. The httpbin server is single-threaded, so keep concurrency in tests low.
|
|
225
|
+
|
|
226
|
+
Set `HTTPPERF_PROFILE=1` when building to instrument the extension. See [docs/profiling.md](docs/profiling.md).
|
|
227
|
+
|
|
228
|
+
## Licence
|
|
229
|
+
|
|
230
|
+
MIT. See [LICENSE](LICENSE). [NOTICE](NOTICE) covers the bundled Redis event library and the libraries included in the binary wheels.
|