tigrcorn-runtime 0.3.16.dev5__py3-none-any.whl

tigrcorn_runtime/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+__all__ = [
+    "run",
+    "serve",
+    "serve_import_string",
+]
+
+
+def __getattr__(name: str):
+    if name in __all__:
+        from .api import run, serve, serve_import_string
+
+        mapping = {
+            "run": run,
+            "serve": serve,
+            "serve_import_string": serve_import_string,
+        }
+        return mapping[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tigrcorn_runtime/api.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import asyncio
+from typing import cast
+
+from tigrcorn_config.load import build_config
+from tigrcorn_config.model import ServerConfig
+from tigrcorn_runtime.server.app_loader import load_app
+from tigrcorn_runtime.server.bootstrap import run_coro_with_runtime
+from tigrcorn_runtime.server.runner import TigrCornServer
+from tigrcorn_runtime.server.signals import install_signal_handlers
+from tigrcorn_core.types import ASGIApp
+
+
+async def serve(
+    app: ASGIApp,
+    *,
+    profile: str | None = None,
+    app_interface: str = "auto",
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    uds: str | None = None,
+    transport: str = "tcp",
+    lifespan: str = "auto",
+    log_level: str = "info",
+    access_log: bool = True,
+    ssl_certfile: str | None = None,
+    ssl_keyfile: str | None = None,
+    ssl_keyfile_password: str | bytes | None = None,
+    ssl_ca_certs: str | None = None,
+    ssl_require_client_cert: bool | None = None,
+    ssl_ciphers: str | None = None,
+    ssl_crl: str | None = None,
+    http_versions: list[str] | None = None,
+    websocket: bool | None = None,
+    enable_h2c: bool = False,
+    max_body_size: int | None = None,
+    protocols: list[str] | None = None,
+    quic_secret: bytes | None = None,
+    quic_require_retry: bool | None = None,
+    pipe_mode: str = "rawframed",
+    config: ServerConfig | None = None,
+) -> None:
+    """Serve an ASGI application until shutdown is requested.
+
+    Args:
+        app: ASGI application callable to run.
+        profile: Optional packaged profile name.
+        app_interface: Application interface selection mode.
+        host: TCP host when the TCP transport is active.
+        port: TCP port when the TCP transport is active.
+        uds: Unix-domain socket path when the Unix transport is active.
+        transport: Listener transport family.
+        lifespan: Lifespan negotiation policy.
+        log_level: Runtime logging level.
+        access_log: Whether access logging is enabled.
+        ssl_certfile: Server certificate file path.
+        ssl_keyfile: Server private key file path.
+        ssl_keyfile_password: Optional private key password.
+        ssl_ca_certs: Optional trust-anchor bundle for peer validation.
+        ssl_require_client_cert: Whether client certificates are required.
+        ssl_ciphers: Optional TLS cipher policy.
+        ssl_crl: Optional certificate revocation list file.
+        http_versions: Enabled HTTP protocol versions.
+        websocket: Whether WebSocket handling is enabled.
+        enable_h2c: Whether cleartext HTTP/2 upgrade is enabled.
+        max_body_size: Optional request-body size cap.
+        protocols: Enabled runtime protocol families.
+        quic_secret: Optional QUIC retry/integrity secret.
+        quic_require_retry: Whether QUIC retry is required.
+        pipe_mode: Pipe listener framing mode.
+        config: Prebuilt server configuration. Other options are used only
+            when this is not supplied.
+
+    Returns:
+        None.
+    """
+
+    if config is None:
+        config = build_config(
+            profile=profile,
+            app_interface=app_interface,
+            host=host,
+            port=port,
+            uds=uds,
+            transport=transport,
+            lifespan=lifespan,
+            log_level=log_level,
+            access_log=access_log,
+            ssl_certfile=ssl_certfile,
+            ssl_keyfile=ssl_keyfile,
+            ssl_keyfile_password=ssl_keyfile_password,
+            ssl_ca_certs=ssl_ca_certs,
+            ssl_require_client_cert=ssl_require_client_cert,
+            ssl_ciphers=ssl_ciphers,
+            ssl_crl=ssl_crl,
+            http_versions=http_versions,
+            websocket=websocket,
+            enable_h2c=enable_h2c,
+            max_body_size=max_body_size,
+            protocols=protocols,
+            quic_secret=quic_secret,
+            quic_require_retry=quic_require_retry,
+            pipe_mode=pipe_mode,
+        )
+    server = TigrCornServer(app=app, config=config)
+    install_signal_handlers(asyncio.get_running_loop(), server.request_shutdown)
+    await server.serve_forever()
+
+
+async def serve_import_string(
+    app_target: str | None = None,
+    *,
+    profile: str | None = None,
+    app_interface: str = "auto",
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    uds: str | None = None,
+    transport: str = "tcp",
+    lifespan: str = "auto",
+    log_level: str = "info",
+    access_log: bool = True,
+    ssl_certfile: str | None = None,
+    ssl_keyfile: str | None = None,
+    ssl_keyfile_password: str | bytes | None = None,
+    ssl_ca_certs: str | None = None,
+    ssl_require_client_cert: bool | None = None,
+    ssl_ciphers: str | None = None,
+    ssl_crl: str | None = None,
+    http_versions: list[str] | None = None,
+    websocket: bool | None = None,
+    enable_h2c: bool = False,
+    max_body_size: int | None = None,
+    protocols: list[str] | None = None,
+    quic_secret: bytes | None = None,
+    quic_require_retry: bool | None = None,
+    pipe_mode: str = "rawframed",
+    factory: bool = False,
+    config: ServerConfig | None = None,
+) -> None:
+    """Load an ASGI application by import string and serve it.
+
+    Args:
+        app_target: Import target such as ``module:app``.
+        profile: Optional packaged profile name.
+        app_interface: Application interface selection mode.
+        host: TCP host when the TCP transport is active.
+        port: TCP port when the TCP transport is active.
+        uds: Unix-domain socket path when the Unix transport is active.
+        transport: Listener transport family.
+        lifespan: Lifespan negotiation policy.
+        log_level: Runtime logging level.
+        access_log: Whether access logging is enabled.
+        ssl_certfile: Server certificate file path.
+        ssl_keyfile: Server private key file path.
+        ssl_keyfile_password: Optional private key password.
+        ssl_ca_certs: Optional trust-anchor bundle for peer validation.
+        ssl_require_client_cert: Whether client certificates are required.
+        ssl_ciphers: Optional TLS cipher policy.
+        ssl_crl: Optional certificate revocation list file.
+        http_versions: Enabled HTTP protocol versions.
+        websocket: Whether WebSocket handling is enabled.
+        enable_h2c: Whether cleartext HTTP/2 upgrade is enabled.
+        max_body_size: Optional request-body size cap.
+        protocols: Enabled runtime protocol families.
+        quic_secret: Optional QUIC retry/integrity secret.
+        quic_require_retry: Whether QUIC retry is required.
+        pipe_mode: Pipe listener framing mode.
+        factory: Whether the import target is an application factory.
+        config: Prebuilt server configuration. Its application target is used
+            when ``app_target`` is not supplied.
+
+    Returns:
+        None.
+
+    Raises:
+        ValueError: If no import target is supplied by arguments or config.
+    """
+
+    if config is not None:
+        app_target = app_target or config.app.target
+        factory = config.app.factory if factory is False else factory
+    if app_target is None:
+        raise ValueError("app_target is required when config.app.target is not set")
+    app_dir = config.app.app_dir if config is not None else None
+    if app_dir is None:
+        app = load_app(app_target, factory=factory)
+    else:
+        app = load_app(app_target, factory=factory, app_dir=app_dir)
+    await serve(
+        cast(ASGIApp, app),
+        profile=profile,
+        app_interface=app_interface,
+        host=host,
+        port=port,
+        uds=uds,
+        transport=transport,
+        lifespan=lifespan,
+        log_level=log_level,
+        access_log=access_log,
+        ssl_certfile=ssl_certfile,
+        ssl_keyfile=ssl_keyfile,
+        ssl_keyfile_password=ssl_keyfile_password,
+        ssl_ca_certs=ssl_ca_certs,
+        ssl_require_client_cert=ssl_require_client_cert,
+        ssl_ciphers=ssl_ciphers,
+        ssl_crl=ssl_crl,
+        http_versions=http_versions,
+        websocket=websocket,
+        enable_h2c=enable_h2c,
+        max_body_size=max_body_size,
+        protocols=protocols,
+        quic_secret=quic_secret,
+        quic_require_retry=quic_require_retry,
+        pipe_mode=pipe_mode,
+        config=config,
+    )
+
+
+def run(
+    app: ASGIApp | str,
+    *,
+    profile: str | None = None,
+    app_interface: str = "auto",
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    uds: str | None = None,
+    transport: str = "tcp",
+    lifespan: str = "auto",
+    log_level: str = "info",
+    access_log: bool = True,
+    ssl_certfile: str | None = None,
+    ssl_keyfile: str | None = None,
+    ssl_keyfile_password: str | bytes | None = None,
+    ssl_ca_certs: str | None = None,
+    ssl_require_client_cert: bool | None = None,
+    ssl_ciphers: str | None = None,
+    ssl_crl: str | None = None,
+    http_versions: list[str] | None = None,
+    websocket: bool | None = None,
+    enable_h2c: bool = False,
+    max_body_size: int | None = None,
+    protocols: list[str] | None = None,
+    quic_secret: bytes | None = None,
+    quic_require_retry: bool | None = None,
+    pipe_mode: str = "rawframed",
+    factory: bool = False,
+    config: ServerConfig | None = None,
+) -> None:
+    """Run an ASGI application or import target from synchronous code.
+
+    Args:
+        app: ASGI application callable or import target.
+        profile: Optional packaged profile name.
+        app_interface: Application interface selection mode.
+        host: TCP host when the TCP transport is active.
+        port: TCP port when the TCP transport is active.
+        uds: Unix-domain socket path when the Unix transport is active.
+        transport: Listener transport family.
+        lifespan: Lifespan negotiation policy.
+        log_level: Runtime logging level.
+        access_log: Whether access logging is enabled.
+        ssl_certfile: Server certificate file path.
+        ssl_keyfile: Server private key file path.
+        ssl_keyfile_password: Optional private key password.
+        ssl_ca_certs: Optional trust-anchor bundle for peer validation.
+        ssl_require_client_cert: Whether client certificates are required.
+        ssl_ciphers: Optional TLS cipher policy.
+        ssl_crl: Optional certificate revocation list file.
+        http_versions: Enabled HTTP protocol versions.
+        websocket: Whether WebSocket handling is enabled.
+        enable_h2c: Whether cleartext HTTP/2 upgrade is enabled.
+        max_body_size: Optional request-body size cap.
+        protocols: Enabled runtime protocol families.
+        quic_secret: Optional QUIC retry/integrity secret.
+        quic_require_retry: Whether QUIC retry is required.
+        pipe_mode: Pipe listener framing mode.
+        factory: Whether a string import target is an application factory.
+        config: Prebuilt server configuration. Its process runtime selects
+            the async backend when supplied.
+
+    Returns:
+        None.
+    """
+
+    runtime = config.process.runtime if config is not None else 'auto'
+    if isinstance(app, str):
+        run_coro_with_runtime(
+            lambda: serve_import_string(
+                app,
+                profile=profile,
+                app_interface=app_interface,
+                host=host,
+                port=port,
+                uds=uds,
+                transport=transport,
+                lifespan=lifespan,
+                log_level=log_level,
+                access_log=access_log,
+                ssl_certfile=ssl_certfile,
+                ssl_keyfile=ssl_keyfile,
+                ssl_keyfile_password=ssl_keyfile_password,
+                ssl_ca_certs=ssl_ca_certs,
+                ssl_require_client_cert=ssl_require_client_cert,
+                ssl_ciphers=ssl_ciphers,
+                ssl_crl=ssl_crl,
+                http_versions=http_versions,
+                websocket=websocket,
+                enable_h2c=enable_h2c,
+                max_body_size=max_body_size,
+                protocols=protocols,
+                quic_secret=quic_secret,
+                quic_require_retry=quic_require_retry,
+                pipe_mode=pipe_mode,
+                factory=factory,
+                config=config,
+            ),
+            runtime=runtime,
+        )
+    else:
+        run_coro_with_runtime(
+            lambda: serve(
+                app,
+                profile=profile,
+                app_interface=app_interface,
+                host=host,
+                port=port,
+                uds=uds,
+                transport=transport,
+                lifespan=lifespan,
+                log_level=log_level,
+                access_log=access_log,
+                ssl_certfile=ssl_certfile,
+                ssl_keyfile=ssl_keyfile,
+                ssl_keyfile_password=ssl_keyfile_password,
+                ssl_ca_certs=ssl_ca_certs,
+                ssl_require_client_cert=ssl_require_client_cert,
+                ssl_ciphers=ssl_ciphers,
+                ssl_crl=ssl_crl,
+                http_versions=http_versions,
+                websocket=websocket,
+                enable_h2c=enable_h2c,
+                max_body_size=max_body_size,
+                protocols=protocols,
+                quic_secret=quic_secret,
+                quic_require_retry=quic_require_retry,
+                pipe_mode=pipe_mode,
+                config=config,
+            ),
+            runtime=runtime,
+        )

tigrcorn_runtime/app_interfaces.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Literal
+
+from tigrcorn_compat.asgi3 import assert_asgi3_app, describe_app
+from tigrcorn_core.types import ASGIApp, Message, Scope
+
+AppInterface = Literal["auto", "tigr-asgi-contract", "asgi3"]
+APP_INTERFACE_VALUES: tuple[AppInterface, ...] = ("auto", "tigr-asgi-contract", "asgi3")
+
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+
+
+class AppInterfaceError(TypeError):
+    """Raised when an app cannot be safely bound to the selected interface."""
+
+
+@dataclass(slots=True)
+class NativeContractApp:
+    app: Any
+    capabilities: tuple[str, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+    interface: AppInterface = "tigr-asgi-contract"
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        dispatcher = getattr(self.app, "dispatch", None) or getattr(self.app, "handle", None) or self.app
+        result = dispatcher(scope, receive, send)
+        if inspect.isawaitable(result):
+            await result
+
+
+@dataclass(frozen=True, slots=True)
+class DispatchSelection:
+    interface: Literal["tigr-asgi-contract", "asgi3"]
+    app: ASGIApp
+    native: bool
+
+
+def native_contract_app(
+    app: Any,
+    *,
+    capabilities: list[str] | tuple[str, ...] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> NativeContractApp:
+    return NativeContractApp(
+        app=app,
+        capabilities=tuple(capabilities or ()),
+        metadata=dict(metadata or {}),
+    )
+
+
+def mark_native_contract_app(
+    app: Any,
+    *,
+    capabilities: list[str] | tuple[str, ...] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> Any:
+    setattr(app, "__tigrcorn_app_interface__", "tigr-asgi-contract")
+    setattr(app, "__tigrcorn_contract_capabilities__", tuple(capabilities or ()))
+    setattr(app, "__tigrcorn_contract_metadata__", dict(metadata or {}))
+    return app
+
+
+def is_native_contract_app(app: Any) -> bool:
+    return isinstance(app, NativeContractApp) or getattr(app, "__tigrcorn_app_interface__", None) == "tigr-asgi-contract"
+
+
+def _as_native(app: Any) -> NativeContractApp:
+    if isinstance(app, NativeContractApp):
+        return app
+    capabilities = getattr(app, "__tigrcorn_contract_capabilities__", ())
+    metadata = getattr(app, "__tigrcorn_contract_metadata__", {})
+    return native_contract_app(app, capabilities=capabilities, metadata=metadata)
+
+
+def _is_unambiguous_asgi3(app: Any) -> bool:
+    if not callable(app):
+        return False
+    signature = describe_app(app)
+    return signature.parameter_count == 3
+
+
+def resolve_app_dispatch(app: Any, interface: AppInterface = "auto") -> DispatchSelection:
+    if interface not in APP_INTERFACE_VALUES:
+        raise AppInterfaceError(f"unsupported app interface: {interface!r}")
+    if interface == "tigr-asgi-contract":
+        if not is_native_contract_app(app):
+            raise AppInterfaceError("explicit tigr-asgi-contract selection requires a native contract app marker or wrapper")
+        return DispatchSelection("tigr-asgi-contract", _as_native(app), True)
+    if interface == "asgi3":
+        try:
+            assert_asgi3_app(app)
+        except Exception as exc:
+            raise AppInterfaceError("explicit asgi3 selection requires an ASGI 3 callable") from exc
+        return DispatchSelection("asgi3", app, False)
+
+    if is_native_contract_app(app):
+        return DispatchSelection("tigr-asgi-contract", _as_native(app), True)
+    if _is_unambiguous_asgi3(app):
+        assert_asgi3_app(app)
+        return DispatchSelection("asgi3", app, False)
+    raise AppInterfaceError("ambiguous or unsupported application interface; select asgi3 or tigr-asgi-contract explicitly")