runtime

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

`port_is_available`(host, port, *[, socket_factory])	Return `True` when a host/port has no active listener and can bind.
`find_available_port`([host, start, end, is_available])	Find the first available TCP port in `start..end`.
`find_preferred_auto_port`(host, *[, primary_start, ...])	Find a free port using preferred first, fallback second ranges.
`resolve_server_port`(host, configured_port, *[, ...])	Resolve runtime port using manual config or auto-discovery.
`create_bound_handler_class`(handler_base, *, verbose, ...)	Create handler class bound to runtime verbosity and DB path.
`start_http_server`(settings, *, resolve_port, ...[, ...])	Create a configured `HTTPServer` instance.
`run_server`(settings, *, start_server[, printer])	Run the server until interrupted.

Module Contents

runtime.port_is_available(host, port, *, socket_factory=socket.socket)

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

runtime.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.

runtime.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.

runtime.resolve_server_port(host, configured_port, *, is_available=port_is_available, find_port=None)

Resolve runtime port using manual config or auto-discovery.

Parameters:

host (str) – Bind host for availability checks.
configured_port (int | None) – Optional explicit port from config/CLI.
is_available (Callable[[str, int], bool]) – Port availability predicate.
find_port (Callable[[str, int, int], int] | None) – Optional custom free-port finder.

Returns:

Concrete port to bind.

Raises:

OSError – If no usable port can be resolved.

Return type:

int

runtime.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.

Parameters:

handler_base (type[HandlerT]) – Base handler class to clone.
verbose (bool) – Whether the handler should log requests.
db_path (pathlib.Path) – SQLite database path to bind on the class.
schema_ready (bool) – When True, skip per-request schema checks.
extra_attrs (dict[str, Any] | None) – Optional attribute overrides for specialized handler modes.

runtime.start_http_server(settings, *, resolve_port, create_handler, initialize_storage=None, http_server_cls=None)

Create a configured HTTPServer instance.

Parameters:

settings (pipeworks_name_generation.webapp.config.ServerSettings) – Effective runtime settings.
resolve_port (Callable[[str, int | None], int]) – Host/port resolution callback.
create_handler (Callable[[bool, pathlib.Path], type[http.server.BaseHTTPRequestHandler]]) – Handler factory bound to runtime verbosity and DB path.
initialize_storage (Callable[[pathlib.Path], None] | None) – Optional one-time startup hook for DB/schema prep.
http_server_cls (Callable[[tuple[str, int], type[http.server.BaseHTTPRequestHandler]], Any] | None) – Concrete HTTP server class.

runtime.run_server(settings, *, start_server, printer=print)

Run the server until interrupted.

Parameters:

settings (pipeworks_name_generation.webapp.config.ServerSettings) – Effective runtime settings from config and CLI overrides.
start_server (Callable[[pipeworks_name_generation.webapp.config.ServerSettings], tuple[Any, int]]) – Factory that returns (server, port).
printer (Callable[[str], None]) – Output callable used for startup/shutdown messages.

Returns:

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

Return type:

int