Tigrcorn

ASGI3 server with built-in HTTP/1.1, HTTP/2, HTTP/3, QUIC, WebSocket, TLS, static delivery, and release validation.

---

Release status

Package

Protocol status

Operator and API surface status

---

Tigrcorn is an ASGI3 server for Python teams building APIs, edge services, internal platforms, and protocol-heavy applications that need modern transport support without giving up operational control. It implements HTTP/1.1, HTTP/2, HTTP/3, QUIC, WebSockets, TLS handling, static delivery, and release checks inside the project, with operator docs and current-state material kept alongside the code.

Most users should start with Quick start, Protocol and feature map, and CLI usage. Maintainers should use the SSOT, governance, and conformance links when changing claimed support, release boundaries, or certification evidence.

Table of contents

• Legend
• Choose your path
• Quick start
• Why teams pick Tigrcorn
• What Tigrcorn provides
• Published packages
• Installation and extras
• Protocol and feature map
• CLI usage
• Public API and embedding usage
• Current scope
• Status at a glance
• Validation and promotion
• Where to look
• Contributing, conduct, and community norms
• Footnotes

Legend

Use this legend for the badges, status tables, and scope markers in this README.

Marker	Meaning
C-RFC	included in Tigrcorn's current certified RFC boundary
C-OP	included in Tigrcorn's current public operator/API surface
OOB	outside Tigrcorn's current documented boundary and shipped surface
green	the referenced repo contract or evaluation target is currently passing
canonical	the referenced document is the current mutable source of truth
repo_line	the active repository release line represented by this checkout
runtime-auto, runtime-asyncio, runtime-uvloop	documented runtime modes in the current public surface

The top badge groups use plain language labels where possible. The protocol and feature tables use C-RFC, C-OP, and OOB as compact scope markers.

Choose your path

Goal	Start with	Then use
Run Tigrcorn as an ASGI server	Quick start	CLI docs, deployment profiles
Configure production behavior	CLI docs	defaults, observability, policies
Build on Tigrcorn from Python	Public API and embedding usage	public API docs, lifecycle and embedded server guide
Understand protocol and feature support	Protocol and feature map	protocol docs, certification boundary, .ssot/registry.json
Review release and conformance status	Status at a glance	Validation and promotion, conformance docs

Quick start

Install

python -m pip install tigrcorn

Run an HTTP server

tigrcorn examples.echo_http.app:app --host 127.0.0.1 --port 8000

Run HTTP/3 + QUIC

tigrcorn examples.echo_http.app:app \
  --quic-bind 127.0.0.1:8443 \
  --http 3 \
  --protocol http3 \
  --protocol quic \
  --ssl-certfile ./certs/server.pem \
  --ssl-keyfile ./certs/server.key

Run from Python

from tigrcorn import run

run("examples.echo_http.app:app", host="127.0.0.1", port=8000)

For complete operator recipes, use CLI docs. For public imports and lifecycle details, use public API docs and lifecycle and embedded server guide. For the blessed safe deployment profiles, use deployment profiles and the packaged profile artifacts.

Why teams pick Tigrcorn

• Modern protocol stack in the server itself. HTTP/1.1, HTTP/2, HTTP/3, QUIC, WebSockets, TLS 1.3, ALPN, X.509 validation, OCSP, and CRL handling are first-class documented surfaces.
• Operator features that matter in deployment. Listener binding, TLS and QUIC controls, workers, reload, structured logging, metrics, proxy normalization, content-coding policy, CONNECT policy, Early Hints, Alt-Svc, and static delivery are part of the public surface.
• A public Python API for applications and hosts. run, serve, serve_import_string, EmbeddedServer, StaticFilesApp, and the config helpers are documented as importable entrypoints.
• Static delivery and entity semantics built into the package. Static mounting, precompressed sidecars, conditional requests, range requests, and response-path helpers are available without a separate static server wrapper.
• Release and promotion checks in the repo. evaluate_release_gates and evaluate_promotion_target are shipped APIs, and the repo preserves current-state and promoted-release material under conformance docs.

What Tigrcorn provides

Area	What you get	Primary docs
Server runtime	ASGI3 execution over HTTP/1.1, HTTP/2, HTTP/3, QUIC, and WebSockets	protocol docs, examples
Security	TLS 1.3 controls, ALPN, certificate validation, OCSP, CRL handling	certification boundary
Delivery	static files, ETag/conditional handling, range support, content coding, Early Hints, Alt-Svc	public API docs, deployment profiles reference
Operations	listeners, workers, reload, metrics, logging, proxy normalization, timeouts and resource controls	CLI docs
Embedding	run, serve, serve_import_string, EmbeddedServer, lifecycle hooks	public API docs, lifecycle and embedded server guide
Config	typed config model, config-file loading, env loading, merge from CLI/env/file/defaults	public API docs, CLI docs
Blessed profiles	generated safe deployment profiles plus profile conformance bundles	deployment profiles, profile bundles JSON
Release checks	release-gate and promotion-target evaluators	release workflow guide, public API docs
Current-state and release records	canonical current-state docs plus frozen promoted roots	state docs index, release roots

Published packages

Python package family

Package	Owns
tigrcorn	aggregate distribution and compatibility umbrella
tigrcorn-core	constants, errors, types, and shared utils
tigrcorn-config	config models, validation, profiles, env and file loading
tigrcorn-http	entity tags, headers, conditional requests, ranges, and HTTP helpers
tigrcorn-asgi	ASGI send and receive adapters and response materialization
tigrcorn-contract	event ordering, scope validation, and ASGI contract helpers
tigrcorn-transports	TCP, UDP, Unix, pipe, and transport machinery
tigrcorn-security	TLS, ALPN, X.509, OCSP, and CRL handling
tigrcorn-protocols	HTTP/1.1, HTTP/2, HTTP/3, QUIC, sessions, streams, and schedulers
tigrcorn-static	static delivery and route mounting
tigrcorn-observability	metrics and logging surfaces
tigrcorn-runtime	app loading, runner, workers, reload, embedding, and CLI
tigrcorn-compat	root-namespace shims and promotion helpers
tigrcorn-certification	release gates, strict promotion checks, and external evidence rails

npm package

Package	Owns
@tigrcorn/wt-peer-probes	browser-side WebTransport probe execution and Playwright peer validation

Installation and extras

Base install

python -m pip install tigrcorn

Certification / development install

python -m pip install -e ".[certification,dev]"

Optional extras

Extra	Status	Use it for
tls-x509	supported	package-owned TLS/X.509 validation, certificate handling, and revocation helpers
config-yaml	supported	.yaml / .yml config loading
compression	supported	Brotli content coding and .br sidecars
runtime-uvloop	supported	--runtime uvloop on supported platforms
runtime-trio	declared, not supported	reserved dependency path only
full-featured	supported	current aggregate optional operator feature surface
certification	supported	interop and certification tooling
dev	supported	local development and validation

Practical install examples

# TLS/X.509 validation and certificate-material helpers
python -m pip install -e ".[tls-x509]"

# YAML config support
python -m pip install -e ".[config-yaml]"

# Brotli + precompressed static sidecars
python -m pip install -e ".[compression]"

# uvloop runtime option (non-Windows)
python -m pip install -e ".[runtime-uvloop]"

# current aggregate optional feature surface
python -m pip install -e ".[full-featured]"

The authoritative optional dependency reference is optional dependency surface. TLS/X.509 operations rely on the optional tigrcorn[tls-x509] extra.

Protocol and feature map

This section is a public support snapshot. It keeps protocol and feature details visible in the README while making Tigrcorn's depth, feature surface, and domain coverage explicit. Use C-RFC for current certified protocol claims, C-OP for current operator/API surfaces, and OOB for intentionally out-of-boundary behavior.

Legend: C-RFC = inside the current certified RFC boundary · C-OP = inside the public/operator surface · OOB = outside the current scope

Core protocol, transport, and delivery

Category	Surface	Status	Primary docs
HTTP	HTTP/1.1 (RFC 9112)	C-RFC	HTTP/1.1 docs
HTTP	HTTP/2 (RFC 9113)	C-RFC	HTTP/2 docs
HTTP	HTTP/3 (RFC 9114)	C-RFC	HTTP/3 docs
QUIC	QUIC transport (RFC 9000, RFC 9001, RFC 9002)	C-RFC	QUIC docs
WebSocket	RFC 6455 / RFC 8441 / RFC 9220 carriers	C-RFC	WebSocket docs
Delivery	CONNECT relay, trailer fields, content coding	C-RFC	deployment profiles reference
Delivery	Conditional requests, range requests, Early Hints, bounded Alt-Svc	C-RFC	RFC applicability and competitor status
Security	TLS 1.3, ALPN, X.509, OCSP, CRL	C-RFC	certification boundary

Operator and public API surface

Category	Surface	Status	Primary docs
CLI	tigrcorn, python -m tigrcorn, tigrcorn-interop	C-OP	CLI docs
Config	build_config, build_config_from_namespace, build_config_from_sources	C-OP	public API docs
Embedding	EmbeddedServer, lifecycle hooks, public lifecycle contract	C-OP	lifecycle and embedded server guide
Static	StaticFilesApp, mount_static_app, static route flags	C-OP	public API docs
Operations	reload, workers, runtime selection, metrics, logging, proxy normalization	C-OP	CLI docs
Release	evaluate_release_gates, evaluate_promotion_target	C-OP	public API docs, release workflow guide
Custom transports	pipe / inproc / rawframed / custom	C-OP with boundary notes	custom transport docs, boundary non-goals

CLI usage

The main command is tigrcorn. The public module entrypoint is python -m tigrcorn. The interoperability runner is tigrcorn-interop.

For complete operator coverage, use:

• CLI docs
• CLI flag surface
• CLI flag surface JSON
• deployment profiles reference
• current CLI help snapshot
• current interop help snapshot

Config precedence

CLI > env > config file > defaults

That precedence is implemented by build_config_from_sources and documented in code governance.

Common launch patterns

Minimal HTTP/1.1 + HTTP/2

tigrcorn examples.echo_http.app:app --host 127.0.0.1 --port 8000

App factory loading

tigrcorn examples.echo_http.app:create_app --factory --host 127.0.0.1 --port 8000

Config file + environment merge

tigrcorn examples.echo_http.app:app \
  --config ./tigrcorn.toml \
  --env-file ./.env \
  --env-prefix TIGRCORN

HTTP/2 over TLS

tigrcorn examples.echo_http.app:app \
  --bind 127.0.0.1:8443 \
  --http 2 \
  --ssl-certfile ./certs/server.pem \
  --ssl-keyfile ./certs/server.key

HTTP/3 / QUIC

tigrcorn examples.echo_http.app:app \
  --quic-bind 127.0.0.1:8443 \
  --http 3 \
  --protocol http3 \
  --protocol quic \
  --ssl-certfile ./certs/server.pem \
  --ssl-keyfile ./certs/server.key

WebSocket compression

tigrcorn examples.websocket_echo.app:app \
  --host 127.0.0.1 \
  --port 9000 \
  --websocket-compression permessage-deflate

Static route mounting

tigrcorn examples.http_entity_static.app:app \
  --static-path-route /assets \
  --static-path-mount ./public \
  --static-path-dir-to-file \
  --static-path-index-file index.html \
  --static-path-expires 3600

CONNECT, trailer, and content-coding policy

tigrcorn examples.echo_http.app:app \
  --connect-policy allowlist \
  --connect-allow 127.0.0.1:5432 \
  --trailer-policy strict \
  --content-coding-policy allowlist \
  --content-codings br,gzip,deflate

Automatic Alt-Svc advertisement

tigrcorn examples.advanced_protocol_delivery.alt_svc_app:app \
  --bind 127.0.0.1:8080 \
  --quic-bind 127.0.0.1:8443 \
  --http 1.1 --http 2 --http 3 \
  --alt-svc-auto \
  --alt-svc-ma 86400 \
  --alt-svc-persist

Metrics, logging, reload, and workers

tigrcorn examples.echo_http.app:app \
  --log-level info \
  --structured-log \
  --metrics \
  --metrics-bind 127.0.0.1:9100 \
  --workers 4 \
  --runtime auto \
  --reload \
  --reload-dir ./src

Unix sockets and custom transports

tigrcorn examples.echo_http.app:app \
  --transport unix \
  --uds /tmp/tigrcorn.sock

tigrcorn examples.echo_http.app:app \
  --transport pipe \
  --pipe-mode rawframed \
  --protocol rawframed

Interoperability matrices

tigrcorn-interop \
  --matrix docs/review/conformance/external_matrix.release.json \
  --output ./artifacts/interop

Use current-release external matrix for the current-release bundle contract and same-stack replay matrix for same-stack replay coverage.

Public API and embedding usage

The public import surface is documented in full in public API docs. Lifecycle guarantees for embedded use live in lifecycle and embedded server guide.

Public import map

Import surface	What it is for
tigrcorn.run	sync convenience entrypoint
tigrcorn.serve	async entrypoint for an in-memory ASGI app
tigrcorn.serve_import_string	async entrypoint for an import string
tigrcorn.EmbeddedServer	explicit embedding and lifecycle control
tigrcorn.StaticFilesApp	standalone static ASGI app
tigrcorn.static.mount_static_app	mount static delivery into another ASGI app
tigrcorn.static.normalize_static_route	normalize public static route input
tigrcorn.config.build_config	build ServerConfig from explicit keyword args
tigrcorn.config.build_config_from_namespace	convert argparse namespace into config
tigrcorn.config.build_config_from_sources	merge CLI overrides, config file, and environment
tigrcorn.config.config_to_dict	inspect or serialize config
tigrcorn.config.load_env_config	load prefixed environment config
tigrcorn.config.load_config_file	load TOML / JSON / optional YAML config
tigrcorn.compat.release_gates.evaluate_release_gates	evaluate release-gate readiness
tigrcorn.compat.release_gates.evaluate_promotion_target	evaluate promotion-target readiness
tigrcorn.compat.release_gates.assert_release_ready	fail fast if release gates are not satisfied
tigrcorn.compat.release_gates.assert_promotion_target_ready	fail fast if promotion target is not satisfied

Usage snippets

Run from sync code

from tigrcorn import run

run(
    "examples.echo_http.app:app",
    host="127.0.0.1",
    port=8000,
    http_versions=["1.1", "2"],
)

Run inside an existing event loop

from tigrcorn import serve

async def app(scope, receive, send):
    ...

await serve(app, host="127.0.0.1", port=8000)

Load an import string inside async code

from tigrcorn import serve_import_string

await serve_import_string(
    "examples.websocket_echo.app:app",
    host="127.0.0.1",
    port=9000,
)

Embed the server and control lifecycle directly

from tigrcorn import EmbeddedServer
from tigrcorn.config import build_config

config = build_config(host="127.0.0.1", port=0, lifespan="on")

async with EmbeddedServer(app, config) as embedded:
    print(embedded.listeners)
    print(embedded.bound_endpoints())

Mount static delivery

from tigrcorn.static import mount_static_app

app = mount_static_app(
    app,
    route="/assets",
    directory="./public",
    apply_content_coding=True,
    content_coding_policy="allowlist",
)

Build config from sources

from tigrcorn.config import build_config_from_sources

config = build_config_from_sources(
    config_path="./tigrcorn.toml",
    env_prefix="TIGRCORN",
    env_file=".env",
    cli_overrides={
        "app": {"target": "examples.echo_http.app:app"},
        "logging": {"level": "debug"},
    },
)

Evaluate release and promotion state

from tigrcorn.compat.release_gates import evaluate_promotion_target, evaluate_release_gates

release_report = evaluate_release_gates(".")
promotion_report = evaluate_promotion_target(".")

print(release_report.passed)
print(promotion_report.passed)

Current scope

Current supported runtime surface

Runtime	Status	Source
auto	supported	certification boundary
asyncio	supported	certification boundary
uvloop	supported	certification boundary, optional dependency surface
trio	reserved dependency path, not supported	boundary non-goals

Out-of-boundary families

Family	Current location
Trio as a supported runtime family	boundary non-goals
WSGI / ASGI2 / RSGI compatibility layers	boundary non-goals
Parser pluggability	boundary non-goals
WebSocket engine pluggability	boundary non-goals
RFC 9111 caching	RFC applicability and competitor status
RFC 9530 digest fields	RFC applicability and competitor status
RFC 9421 message signatures	RFC applicability and competitor status
JOSE / COSE layers	RFC applicability and competitor status

Status at a glance

Topic	Current source of truth
Repo line	0.3.16.dev5 in pyproject.toml and the shipped facade import surface
Current state	current repository state
Canonical machine-readable registry	.ssot/registry.json
Current-state chain	current-state chain, current-state chain JSON
Authoritative boundary	certification boundary
Strict profile	strict profile target
Canonical promoted root	canonical promoted root
Operator docs	operator docs, CLI docs, public API docs
Lifecycle and embedding contract	lifecycle and embedded server guide
Optional dependency truth	optional dependency surface, optional dependency surface JSON
External evidence inputs	same-stack replay matrix, release external matrix, current-release external matrix
Planning and promotion checkpoints	Phase 9 implementation plan, Phase 9A promotion contract freeze

Current repository claim

Under certification boundary, the package is certifiably fully RFC compliant under the authoritative certification boundary. The canonical promoted root at canonical promoted root is strict-target certifiably fully RFC compliant and certifiably fully featured.¹

Validation and promotion

A practical maintainer validation pass looks like this:

python tools/govchk.py scan
PYTHONPATH=src python -m compileall -q src benchmarks tools
PYTHONPATH=src pytest -q

Promotion-facing evaluators:

PYTHONPATH=src python - <<'PY'
from tigrcorn.compat.release_gates import evaluate_release_gates, evaluate_promotion_target

print(evaluate_release_gates('.').passed)
print(
    evaluate_release_gates(
        '.',
        boundary_path='docs/review/conformance/certification_boundary.strict_target.json',
    ).passed
)
print(evaluate_promotion_target('.').passed)
PY

Read next:

• release workflow guide
• release gate status
• strict profile target
• flag certification target
• Phase 9A promotion contract freeze

Where to look

If you are...	Start here	Then go to
Launching Tigrcorn as an operator	CLI docs	deployment profiles reference
Embedding Tigrcorn in another process	public API docs	lifecycle and embedded server guide
Working on static or delivery behavior	public API docs	static delivery example
Reviewing current repository truth	current repository state	current-state chain JSON
Reviewing the promoted release root	canonical promoted root	release notes 0.3.9
Reviewing the boundary or current scope	certification boundary	boundary non-goals
Comparing Tigrcorn with peer servers	RFC comparison	CLI comparison, operations comparison, out-of-bound comparison
Writing or maintaining docs	authoring guide	CONTRIBUTING.md, tree rules, mutability rules
Working on release or promotion	release workflow guide	Phase 9A promotion contract freeze

Contributing, conduct, and community norms

• CONTRIBUTING.md explains how to make changes without drifting from the boundary, tests, current-state chain, or release evidence.
• CODE_OF_CONDUCT.md defines participation expectations and reporting guidance.
• authoring guide explains how maintainers and authors should update the repository without creating truth conflicts.
• tree rules and mutability rules explain where new files belong and which trees are frozen.

Footnotes

Footnotes

1. Certification language in this repository is scoped by certification boundary and current repository state. The current package claim and the promoted-root claim are related, but they are not the same statement. ↩