runtime
=======

.. py:module:: runtime

.. autoapi-nested-parse::

   Runtime bootstrap helpers for the webapp server process.

   These helpers isolate bind-port resolution and HTTP server lifecycle behavior so
   ``server.py`` can focus on request handling and high-level orchestration.



Functions
---------

.. autoapisummary::

   runtime.port_is_available
   runtime.find_available_port
   runtime.find_preferred_auto_port
   runtime.resolve_server_port
   runtime.create_bound_handler_class
   runtime.start_http_server
   runtime.run_server


Module Contents
---------------

.. py:function:: port_is_available(host, port, *, socket_factory = socket.socket)

   Return ``True`` when a host/port has no active listener and can bind.


.. py:function:: find_available_port(host = '127.0.0.1', start = 8000, end = 8999, *, is_available = port_is_available)

   Find the first available TCP port in ``start..end``.

   :raises OSError: When no free port is available in the given range.


.. py:function:: find_preferred_auto_port(host, *, primary_start = AUTO_PORT_PRIMARY_START, primary_end = AUTO_PORT_PRIMARY_END, fallback_start = AUTO_PORT_FALLBACK_START, fallback_end = AUTO_PORT_FALLBACK_END, find_in_range = None)

   Find a free port using preferred first, fallback second ranges.

   The server should check the 8000-range first for predictable local
   development behavior, then fall back to the broader range if needed.


.. py:function:: resolve_server_port(host, configured_port, *, is_available = port_is_available, find_port = None)

   Resolve runtime port using manual config or auto-discovery.

   :param host: Bind host for availability checks.
   :param configured_port: Optional explicit port from config/CLI.
   :param is_available: Port availability predicate.
   :param find_port: Optional custom free-port finder.

   :returns: Concrete port to bind.

   :raises OSError: If no usable port can be resolved.


.. py:function:: create_bound_handler_class(handler_base, *, verbose, db_path, schema_ready = False, extra_attrs = None)

   Create handler class bound to runtime verbosity and DB path.

   :param handler_base: Base handler class to clone.
   :param verbose: Whether the handler should log requests.
   :param db_path: SQLite database path to bind on the class.
   :param schema_ready: When ``True``, skip per-request schema checks.
   :param extra_attrs: Optional attribute overrides for specialized handler modes.


.. py:function:: start_http_server(settings, *, resolve_port, create_handler, initialize_storage = None, http_server_cls = None)

   Create a configured ``HTTPServer`` instance.

   :param settings: Effective runtime settings.
   :param resolve_port: Host/port resolution callback.
   :param create_handler: Handler factory bound to runtime verbosity and DB path.
   :param initialize_storage: Optional one-time startup hook for DB/schema prep.
   :param http_server_cls: Concrete HTTP server class.


.. py:function:: run_server(settings, *, start_server, printer = print)

   Run the server until interrupted.

   :param settings: Effective runtime settings from config and CLI overrides.
   :param start_server: Factory that returns ``(server, port)``.
   :param printer: Output callable used for startup/shutdown messages.

   :returns: Process-style exit code (``0`` on normal shutdown).