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.
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.
- Legend
- Choose your path
- 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.
| Goal | Start with | Then use |
|---|---|---|
| Run Tigrcorn as an ASGI server | Quick start | docs/ops/cli.md, docs/ops/profiles.md |
| Configure production behavior | docs/ops/cli.md |
docs/ops/defaults.md, docs/ops/observability.md, docs/ops/policies.md |
| Build on Tigrcorn from Python | Public API and embedding usage | docs/ops/public.md, docs/LIFECYCLE_AND_EMBEDDED_SERVER.md |
| Understand protocol and feature support | Protocol and feature map | docs/protocols/, docs/review/conformance/CERTIFICATION_BOUNDARY.md, .ssot/registry.json |
| Change runtime behavior | .codex/AGENTS.md |
docs/gov/authoring.md, tests/, tools/ssot_sync.py |
| Change claimed support or release truth | .ssot/registry.json |
.ssot/adr/, .ssot/specs/, docs/review/conformance/ |
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 packaged src/tigrcorn/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.
This section is a public support snapshot. It keeps protocol and feature details visible in the README, but it does not replace the deeper truth surfaces. Use C-RFC for current certified protocol claims, C-OP for current operator/API surfaces, and O for intentionally out-of-scope behavior. When changing claimed support, update .ssot/registry.json, the related ADR/SPEC/feature/claim/test/evidence rows, and the conformance boundary together.
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/ |
docs/release-notes/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 | .codex/AGENTS.md |
tools/govchk.py |
Maintainer and authoring guidance lives in:
docs/gov/authoring.mdCONTRIBUTING.md.codex/AGENTS.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. ↩
