ASGI3 server with built-in HTTP/1.1, HTTP/2, HTTP/3, QUIC, WebSocket, TLS, static delivery, and release validation.
Operator and API surface status
Tigrcorn is an ASGI3 server for teams that want modern transport and protocol support, explicit operator controls, and a public Python API that matches the shipped runtime. 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.
- Legend
- Quick start
- Why teams pick Tigrcorn
- What Tigrcorn provides
- 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
- Governance and maintainer workflow
- Current-state and historical planning
- Certification environment freeze
- Contributing, conduct, and community norms
- Footnotes
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 |
O |
outside Tigrcorn's current documented scope |
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 O as compact scope markers.
python -m pip install tigrcorntigrcorn examples.echo_http.app:app --host 127.0.0.1 --port 8000tigrcorn 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.keyfrom tigrcorn import run
run("examples.echo_http.app:app", host="127.0.0.1", port=8000)For complete operator recipes, use docs/ops/cli.md. For public imports and lifecycle details, use docs/ops/public.md and docs/LIFECYCLE_AND_EMBEDDED_SERVER.md.
For the blessed safe deployment profiles, use docs/ops/profiles.md and the generated profiles/*.profile.json artifacts.
- 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_gatesandevaluate_promotion_targetare shipped APIs, and the repo preserves current-state and promoted-release material underdocs/review/conformance/.
| Area | What you get | Primary docs |
|---|---|---|
| Server runtime | ASGI3 execution over HTTP/1.1, HTTP/2, HTTP/3, QUIC, and WebSockets | docs/protocols/, examples/ |
| Security | TLS 1.3 controls, ALPN, certificate validation, OCSP, CRL handling | docs/review/conformance/CERTIFICATION_BOUNDARY.md |
| Delivery | static files, ETag/conditional handling, range support, content coding, Early Hints, Alt-Svc | docs/ops/public.md, docs/review/conformance/DEPLOYMENT_PROFILES.md |
| Operations | listeners, workers, reload, metrics, logging, proxy normalization, timeouts and resource controls | docs/ops/cli.md |
| Embedding | run, serve, serve_import_string, EmbeddedServer, lifecycle hooks |
docs/ops/public.md, docs/LIFECYCLE_AND_EMBEDDED_SERVER.md |
| Config | typed config model, config-file loading, env loading, merge from CLI/env/file/defaults | docs/ops/public.md, docs/ops/cli.md |
| Blessed profiles | generated safe deployment profiles plus profile conformance bundles | docs/ops/profiles.md, docs/conformance/profile_bundles.json |
| Release checks | release-gate and promotion-target evaluators | docs/gov/release.md, docs/ops/public.md |
| Current-state and release records | canonical current-state docs plus frozen promoted roots | docs/review/conformance/state/, docs/review/conformance/releases/ |
python -m pip install tigrcornpython -m pip install -e ".[certification,dev]"| 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 |
# 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 docs/review/conformance/OPTIONAL_DEPENDENCY_SURFACE.md. TLS/X.509 operations rely on the optional tigrcorn[tls-x509] extra.
Legend:
C-RFC= inside the current certified RFC boundary ·C-OP= inside the public/operator surface ·O= outside the current scope
| Category | Surface | Status | Primary docs |
|---|---|---|---|
| HTTP | HTTP/1.1 (RFC 9112) |
C-RFC |
docs/protocols/http1.md |
| HTTP | HTTP/2 (RFC 9113) |
C-RFC |
docs/protocols/http2.md |
| HTTP | HTTP/3 (RFC 9114) |
C-RFC |
docs/protocols/http3.md |
| QUIC | QUIC transport (RFC 9000, RFC 9001, RFC 9002) |
C-RFC |
docs/protocols/quic.md |
| WebSocket | RFC 6455 / RFC 8441 / RFC 9220 carriers | C-RFC |
docs/protocols/websocket.md |
| Delivery | CONNECT relay, trailer fields, content coding | C-RFC |
docs/review/conformance/DEPLOYMENT_PROFILES.md |
| Delivery | Conditional requests, range requests, Early Hints, bounded Alt-Svc | C-RFC |
docs/review/conformance/RFC_APPLICABILITY_AND_COMPETITOR_STATUS.md |
| Security | TLS 1.3, ALPN, X.509, OCSP, CRL | C-RFC |
docs/review/conformance/CERTIFICATION_BOUNDARY.md |
| Category | Surface | Status | Primary docs |
|---|---|---|---|
| CLI | tigrcorn, python -m tigrcorn, tigrcorn-interop |
C-OP |
docs/ops/cli.md |
| Config | build_config, build_config_from_namespace, build_config_from_sources |
C-OP |
docs/ops/public.md |
| Embedding | EmbeddedServer, lifecycle hooks, public lifecycle contract |
C-OP |
docs/LIFECYCLE_AND_EMBEDDED_SERVER.md |
| Static | StaticFilesApp, mount_static_app, static route flags |
C-OP |
docs/ops/public.md |
| Operations | reload, workers, runtime selection, metrics, logging, proxy normalization | C-OP |
docs/ops/cli.md |
| Release | evaluate_release_gates, evaluate_promotion_target |
C-OP |
docs/ops/public.md, docs/gov/release.md |
| Custom transports | pipe / inproc / rawframed / custom | C-OP with boundary notes |
docs/protocols/custom-transports.md, docs/review/conformance/BOUNDARY_NON_GOALS.md |
The main command is tigrcorn. The public module entrypoint is python -m tigrcorn. The interoperability runner is tigrcorn-interop.
For complete operator coverage, use:
docs/ops/cli.mddocs/review/conformance/CLI_FLAG_SURFACE.mddocs/review/conformance/cli_flag_surface.jsondocs/review/conformance/DEPLOYMENT_PROFILES.mddocs/review/conformance/cli_help.current.txtdocs/review/conformance/tigrcorn_interop_help.current.txt
CLI > env > config file > defaults
That precedence is implemented by build_config_from_sources and documented in docs/gov/code.md.
tigrcorn examples.echo_http.app:app --host 127.0.0.1 --port 8000tigrcorn examples.echo_http.app:create_app --factory --host 127.0.0.1 --port 8000tigrcorn examples.echo_http.app:app \
--config ./tigrcorn.toml \
--env-file ./.env \
--env-prefix TIGRCORNtigrcorn examples.echo_http.app:app \
--bind 127.0.0.1:8443 \
--http 2 \
--ssl-certfile ./certs/server.pem \
--ssl-keyfile ./certs/server.keytigrcorn 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.keytigrcorn examples.websocket_echo.app:app \
--host 127.0.0.1 \
--port 9000 \
--websocket-compression permessage-deflatetigrcorn 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 3600tigrcorn 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,deflatetigrcorn 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-persisttigrcorn 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 ./srctigrcorn examples.echo_http.app:app \
--transport unix \
--uds /tmp/tigrcorn.socktigrcorn examples.echo_http.app:app \
--transport pipe \
--pipe-mode rawframed \
--protocol rawframedtigrcorn-interop \
--matrix docs/review/conformance/external_matrix.release.json \
--output ./artifacts/interopUse docs/review/conformance/external_matrix.current_release.json for the current-release bundle contract and docs/review/conformance/external_matrix.same_stack_replay.json for same-stack replay coverage.
The public import surface is documented in full in docs/ops/public.md. Lifecycle guarantees for embedded use live in docs/LIFECYCLE_AND_EMBEDDED_SERVER.md.
| 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 |
from tigrcorn import run
run(
"examples.echo_http.app:app",
host="127.0.0.1",
port=8000,
http_versions=["1.1", "2"],
)from tigrcorn import serve
async def app(scope, receive, send):
...
await serve(app, host="127.0.0.1", port=8000)from tigrcorn import serve_import_string
await serve_import_string(
"examples.websocket_echo.app:app",
host="127.0.0.1",
port=9000,
)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())from tigrcorn.static import mount_static_app
app = mount_static_app(
app,
route="/assets",
directory="./public",
apply_content_coding=True,
content_coding_policy="allowlist",
)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"},
},
)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)| Runtime | Status | Source |
|---|---|---|
auto |
supported | docs/review/conformance/CERTIFICATION_BOUNDARY.md |
asyncio |
supported | docs/review/conformance/CERTIFICATION_BOUNDARY.md |
uvloop |
supported | docs/review/conformance/CERTIFICATION_BOUNDARY.md, docs/review/conformance/OPTIONAL_DEPENDENCY_SURFACE.md |
trio |
reserved dependency path, not supported | docs/review/conformance/BOUNDARY_NON_GOALS.md |
| Family | Current location |
|---|---|
| Trio as a supported runtime family | docs/review/conformance/BOUNDARY_NON_GOALS.md |
| WSGI / ASGI2 / RSGI compatibility layers | docs/review/conformance/BOUNDARY_NON_GOALS.md |
| Parser pluggability | docs/review/conformance/BOUNDARY_NON_GOALS.md |
| WebSocket engine pluggability | docs/review/conformance/BOUNDARY_NON_GOALS.md |
| RFC 9111 caching | docs/review/conformance/RFC_APPLICABILITY_AND_COMPETITOR_STATUS.md |
| RFC 9530 digest fields | docs/review/conformance/RFC_APPLICABILITY_AND_COMPETITOR_STATUS.md |
| RFC 9421 message signatures | docs/review/conformance/RFC_APPLICABILITY_AND_COMPETITOR_STATUS.md |
| JOSE / COSE layers | docs/review/conformance/RFC_APPLICABILITY_AND_COMPETITOR_STATUS.md |
| Topic | Current source of truth |
|---|---|
| Repo line | 0.3.9 in pyproject.toml and src/tigrcorn/version.py |
| Current state | docs/review/conformance/state/CURRENT_REPOSITORY_STATE.md |
| Canonical machine-readable registry | .ssot/registry.json |
| Current-state chain | docs/review/conformance/CURRENT_STATE_CHAIN.md, docs/review/conformance/current_state_chain.current.json |
| Authoritative boundary | docs/review/conformance/CERTIFICATION_BOUNDARY.md |
| Strict profile | docs/review/conformance/STRICT_PROFILE_TARGET.md |
| Canonical promoted root | docs/review/conformance/releases/0.3.9/release-0.3.9/ |
| Operator docs | docs/ops/README.md, docs/ops/cli.md, docs/ops/public.md |
| Lifecycle and embedding contract | docs/LIFECYCLE_AND_EMBEDDED_SERVER.md |
| Optional dependency truth | docs/review/conformance/OPTIONAL_DEPENDENCY_SURFACE.md, docs/review/conformance/optional_dependency_surface.current.json |
| External evidence inputs | external_matrix.same_stack_replay.json, external_matrix.release.json, external_matrix.current_release.json |
| Planning and promotion checkpoints | docs/review/conformance/PHASE9_IMPLEMENTATION_PLAN.md, docs/review/conformance/PHASE9A_PROMOTION_CONTRACT_FREEZE.md |
Under docs/review/conformance/CERTIFICATION_BOUNDARY.md, the package is certifiably fully RFC compliant under the authoritative certification boundary. The canonical promoted root at docs/review/conformance/releases/0.3.9/release-0.3.9/ is strict-target certifiably fully RFC compliant and certifiably fully featured.1
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 -qPromotion-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)
PYRead next:
docs/gov/release.mddocs/review/conformance/RELEASE_GATE_STATUS.mddocs/review/conformance/STRICT_PROFILE_TARGET.mddocs/review/conformance/FLAG_CERTIFICATION_TARGET.mddocs/review/conformance/PHASE9A_PROMOTION_CONTRACT_FREEZE.md
| If you are… | Start here | Then go to |
|---|---|---|
| Launching Tigrcorn as an operator | docs/ops/cli.md |
docs/review/conformance/DEPLOYMENT_PROFILES.md |
| Embedding Tigrcorn in another process | docs/ops/public.md |
docs/LIFECYCLE_AND_EMBEDDED_SERVER.md |
| Working on static or delivery behavior | docs/ops/public.md |
examples/http_entity_static/app.py |
| Reviewing current repository truth | docs/review/conformance/state/CURRENT_REPOSITORY_STATE.md |
docs/review/conformance/current_state_chain.current.json |
| Reviewing the promoted release root | docs/review/conformance/releases/0.3.9/release-0.3.9/ |
RELEASE_NOTES_0.3.9.md |
| Reviewing the boundary or current scope | docs/review/conformance/CERTIFICATION_BOUNDARY.md |
docs/review/conformance/BOUNDARY_NON_GOALS.md |
| Comparing Tigrcorn with peer servers | docs/comp/rfc.md |
docs/comp/cli.md, docs/comp/ops.md, docs/comp/oob.md |
| Writing or maintaining docs | docs/gov/authoring.md |
CONTRIBUTING.md, docs/gov/tree.md, docs/gov/mut.md |
| Working on release or promotion | docs/gov/release.md |
docs/review/conformance/PHASE9A_PROMOTION_CONTRACT_FREEZE.md |
| Acting as an agent or automation | AGENTS.md |
tools/govchk.py |
Maintainer and authoring guidance lives in:
docs/gov/authoring.mdCONTRIBUTING.mdAGENTS.mddocs/gov/release.md
The short version:
- update code and tests together
- update machine-readable truth together with human docs
- keep current-state pointers current
- create new preserved artifacts for promotion-relevant changes instead of editing a frozen release root
Useful governance checks:
python tools/govchk.py state README.md
python tools/govchk.py state docs/review/conformance/releases/0.3.9
python tools/govchk.py scanRepository cleanliness is governed by MUT.json, docs/gov/tree.md, docs/gov/mut.md, docs/gov/code.md, and ADR .ssot/adr/ADR-1005-doc-gov.md.
For current repository truth, start with:
docs/review/conformance/state/CURRENT_REPOSITORY_STATE.mddocs/review/conformance/state/README.mddocs/review/conformance/CURRENT_STATE_CHAIN.mddocs/review/conformance/current_state_chain.current.json
For planning and promotion history, use:
docs/review/conformance/PHASE9_IMPLEMENTATION_PLAN.mddocs/review/conformance/phase9_implementation_plan.current.jsondocs/review/conformance/PHASE9A_PROMOTION_CONTRACT_FREEZE.mddocs/review/conformance/phase9a_promotion_contract.current.jsondocs/review/conformance/PHASE9A_EXECUTION_BACKLOG.mddocs/review/conformance/phase9a_execution_backlog.current.jsondocs/review/conformance/PHASE9I_RELEASE_ASSEMBLY_AND_CERTIFIABLE_CHECKPOINT.mddocs/review/conformance/phase9i_release_assembly.current.jsondocs/review/conformance/RFC_APPLICABILITY_AND_COMPETITOR_STATUS.mddocs/review/conformance/state/checkpoints/
These files explain how the repository got to the current promoted state without replacing the canonical current-state pointer.
The certification environment freeze documents the install contract and runtime prerequisites for the strict release workflow.
Start with:
docs/review/conformance/CERTIFICATION_ENVIRONMENT_FREEZE.mddocs/review/conformance/certification_environment_freeze.current.jsondocs/review/conformance/delivery/DELIVERY_NOTES_CERTIFICATION_ENVIRONMENT_FREEZE.mddocs/review/conformance/releases/0.3.9/release-0.3.9/tigrcorn-certification-environment-bundle/.github/workflows/phase9-certification-release.ymltools/run_phase9_release_workflow.py
Frozen install command:
python -m pip install -e ".[certification,dev]"The freeze distinguishes the authoritative release-workflow contract from the observed local editing environment.2
CONTRIBUTING.mdexplains how to make changes without drifting from the boundary, tests, current-state chain, or release evidence.CODE_OF_CONDUCT.mddefines participation expectations and reporting guidance.docs/gov/authoring.mdexplains how maintainers and authors should update the repository without creating truth conflicts.docs/gov/tree.mdanddocs/gov/mut.mdexplain where new files belong and which trees are frozen.
Footnotes
-
Certification language in this repository is scoped by
docs/review/conformance/CERTIFICATION_BOUNDARY.mdanddocs/review/conformance/state/CURRENT_REPOSITORY_STATE.md. The current package claim and the promoted-root claim are related, but they are not the same statement. ↩ -
The freeze preserves the release-workflow contract even when the local working environment is missing a certification dependency such as
aioquic. ↩
