Skip to main content

CoAkka HTTP Runtime for Python

CoAkka

CoAkka HTTP Runtime is an embeddable HTTP server and client for Python. Use Python handlers to serve HTTP APIs, stream responses, handle WebSockets or call upstream services. The wheel includes the shared native HTTP core for your platform.

The CoAkka ecosystem provides polyglot tools for distributed applications, HTTP services and logging. CoAkka HTTP Runtime is the HTTP product and can be adopted independently.

CoAkka ecosystem · Raspberry Pi 5 benchmarks

Install 2.2.1

Run these commands from your application directory with CPython 3.11 or newer.

On macOS or Linux:

python3 -m venv .venv
.venv/bin/python -m pip install coakka-http-runtime-python==2.2.1

On Windows in PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install coakka-http-runtime-python==2.2.1

Install coakka-http-runtime-python with pip and import coakka_http in your application.

First request

Save this example as server.py.

from coakka_http import Builder, Request, Response


def echo(request: Request) -> Response:
    return Response(status=201, body=request.body)


def main() -> None:
    service = Builder().listen("127.0.0.1", 8080).post("/echo", echo).start()
    with service:
        print(f"Listening on http://127.0.0.1:{service.port}")
        input("Press Enter to stop. ")


if __name__ == "__main__":
    main()

Run .venv/bin/python server.py on macOS or Linux, or .\.venv\Scripts\python.exe server.py on Windows. From a second terminal, send a request with the following command.

curl -i --data "hello" http://127.0.0.1:8080/echo

In Windows PowerShell, use curl.exe. The server returns HTTP 201 with hello in the response body. Press Enter in the server terminal to shut it down. The service context manager closes the runtime when the block exits.

Requirements

Platform Architecture Requirement
macOS ARM64 macOS 11 or newer
Linux x86-64 and ARM64 glibc 2.28 or newer
Windows x64 and ARM64 CPython matching the wheel architecture

If pip cannot find a matching wheel, run python -VV and python -c "import platform; print(platform.machine())" with the interpreter you plan to use. Install and run the package with that interpreter.

Choose an HTTP version

Builder.listen() in the first example starts a plain HTTP/1.1 listener. For HTTP/2 or HTTP/3, generate the local TLS files and pass a Listener to the builder instead. For example:

from coakka_http import Builder, Listener, ListenerProtocol, TransportSecurity

builder = Builder().listener(
    Listener(
        port=8443,
        protocol=ListenerProtocol.HTTP_2,
        security=TransportSecurity.TLS,
        credential_id="local-example",
        credential_generation=1,
        certificate_chain_file="http-test-tls/server.pem",
        private_key_file="http-test-tls/server.key",
    )
)

Register your routes on builder, then call start(). Use ListenerProtocol.HTTP_3 to serve HTTP/3 over UDP. The complete Python sample runs all 3 modes separately. Python 2.2.1 does not expose the same-port V1 profile.

HTTP/1.1 · HTTP/2 · HTTP/3 · All 3 on one port

Outbound requests

Keep the first server running. Save this example as client.py and run it with the same virtual environment's Python. It sends a request to the configured loopback endpoint and prints 201 hello.

from coakka_http import (
    Builder,
    OutboundEndpoint,
    OutboundReason,
    OutboundRequest,
    OutboundTarget,
)


def main() -> None:
    endpoint = OutboundEndpoint(
        node_id="local",
        connect_host="127.0.0.1",
        connect_port=8080,
        http_authority="127.0.0.1:8080",
    )
    target = OutboundTarget(name="echo", generation=1, endpoints=(endpoint,))

    with Builder().outbound_target(target).start() as service:
        call = service.outbound_submit(
            OutboundRequest("echo", "POST", "/echo", body=b"hello", timeout_ms=3000)
        )
        result = service.take_outbound(5000)
        if result is None:
            raise TimeoutError("No outbound result within five seconds")
        if result.call != call or result.reason is not OutboundReason.RESPONSE:
            raise RuntimeError(f"Outbound request ended with {result.reason.name}")
        print(result.response_status, result.response_body.decode("utf-8"))


if __name__ == "__main__":
    main()

connect_host selects the connection destination and http_authority sets the HTTP authority. For TLS, configure the peer identity and trust for the endpoint. A received HTTP error still arrives as a response with its HTTP status. Use the terminal reason to distinguish transport and lifecycle outcomes.

API reference

Builder creates one service. The service supports buffered and streamed requests, streaming responses and trailers, SSE, WebSockets, static files, outbound targets, generation-checked route updates, TLS and mTLS, and bounded monitoring.

service.routes returns the runtime's route generation and binding revisions. Use effective_limits() and runtime_info() to inspect the configuration accepted by the runtime. Use Builder.compression(Compression(CompressionMode.GZIP)) to enable buffered response compression.

I/O backend

The service uses the platform's default I/O backend. On Linux, applications can request io_uring explicitly.

from coakka_http import Builder, IoBackend, Response

service = (
    Builder()
    .io_backend(IoBackend.IO_URING)
    .get("/health", lambda _request: Response())
    .start()
)
try:
    info = service.runtime_info()
    print(info.io_uring_requested, info.io_uring_effective, info.fallback_reason)
finally:
    service.close()

The native runtime checks availability and uses the platform default when the request cannot be applied. Read io_uring_effective to see the backend in use and fallback_reason for the outcome of the request.

Lower-level API

Runtime accepts one immutable RuntimeConfig and returns copied events.

from coakka_http import EventKind, Response, Route, Runtime, RuntimeConfig

configuration = RuntimeConfig(routes=(Route(41, "POST", "/items/{id}", 101),))
with Runtime(configuration) as runtime:
    runtime.start()
    event = runtime.take_event(5_000)
    if event is not None and event.kind is EventKind.REQUEST:
        runtime.respond(event.exchange, Response(status=202, body=b"accepted"))

Each blocking inbound, WebSocket, outbound, and monitor lane allows one reader. All native views are copied during the call; no borrowed pointer escapes into Python. Failures are NativeError values with a stable numeric status and a bounded diagnostic.

Ownership and bounds

Worker count, queued request count, retained bytes, stream items, handler bindings, active exchanges, monitor pages, and shutdown time are finite. Returning a streaming response gives one callback-scoped writer to its producer. Pressure waits for native recovery credit and retries only the exact rejected item.

Service.close() stops admission, wakes readers, joins connector workers, and destroys native ownership only when no Python code can still reach it. If a handler exceeds the deadline, close raises and retains the owner for a safe retry. The operation is serialized and idempotent.

Monitoring is disabled by default. Enabling it reserves fixed storage during construction. Signals are hints; callers pull immutable snapshots. Monitoring pressure cannot block request handling or change an exchange result.

HTTP Runtime documentation

Metadata

Release files for coakka-http-runtime-python 2.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for coakka-http-runtime-python 2.2.1
File Actions
coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl CPython 3.11 abi3 Windows ARM64 Details for coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl
coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl
coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl CPython 3.11 abi3 Linux glibc 2.28+ x86-64 Details for coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl
coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl CPython 3.11 abi3 Linux glibc 2.28+ ARM64 Details for coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl
coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl

Total release size: 19.5 MB

Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl

Download URL coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl
Size 3.1 MB
Tags CPython 3.11 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
fcf0857871ca5f16d44ec9e8946d2a50447ba118a818565ccb2ec3fb93771061
BLAKE2b-256 checksum
How to use checksums
92ae75e332ac20fcf381ff295a612f943c0338a11285a9f9213cff1dce8b757d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl

Download URL coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl
Size 3.8 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
3efe88269355b023cdc9d7392d671f9878ec10ae92d51eae81c97b6add5ca6ce
BLAKE2b-256 checksum
How to use checksums
6ef97442626a61c72aa0009f67a5951d51201529a5c92beacb713c39282f9e69
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl
Size 4.3 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
e2709aacd0b2127838a5e9faa90224151eff9c0a3bb62fedd12d4638bc5a4b0e
BLAKE2b-256 checksum
How to use checksums
93ba9084a73304a406e2eee1990baf6c7f0d2c05b40f618182a7b9d0d9b3d609
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl
Size 4.6 MB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
c5e0304c73751daee2c79f33172a3daf668e8849809f048af4869872b6f3af6f
BLAKE2b-256 checksum
How to use checksums
f402d708d7f2b65b7b4fdae1d30c69b8cb402739022c0c8a1f3788d42d425036
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl

Download URL coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl
Size 3.5 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
489083f77c1935be5a441aa6b9064c33c36d43da0adccd1839ae1242e541f511
BLAKE2b-256 checksum
How to use checksums
ae6a8a601dc06f8a3878eed9a21a8472ed9e2a819cddb63ae08cd2e7aadb9e0c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Security for coakka-http-runtime-python 2.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page