duck.http.core.httpd.httpd

All utilities and tools a server needs to startup.

This module provides the necessary components for initializing and running a server, including handling requests, managing timeouts, and logging.

Module Contents

Classes

BaseMicroServer

BaseMicroServer class containing definitions for micro application server.

BaseServer

Base server class containing core server definitions and behaviors.

Functions

call_request_handling_executor

This calls the request handling executor with the provided task (thread or coroutine) and the request handling executor keyword arguments set in settings.py.

Data

CONNECTION_MODE

KEEP_ALIVE_PATTERN

KEEP_ALIVE_TIMEOUT

SSL_HANDSHAKE_TIMEOUT

API

class duck.http.core.httpd.httpd.BaseMicroServer(addr: Tuple[str, int], application: Union[duck.app.app.App, duck.app.microapp.MicroApp], domain: str = None, uses_ipv6: bool = False, enable_ssl: bool = False, ssl_params: Optional[Dict] = None, no_logs: bool = False, workers: Optional[int] = None, force_worker_processes: bool = False)

Bases: duck.http.core.httpd.httpd.BaseServer

BaseMicroServer class containing definitions for micro application server.

This class is the base definition of a micro application server.

Initialization

Initialise the server instance.

Parameters:

  • addr – Tuple of address and port.

  • application – The application that is using this server. Can be either duck main app or micro app.

  • domain – The server domain.

  • uses_ipv6 – Whether If the server is on (IPV6)

  • enable_ssl – Whether to enable HTTPS.

  • ssl_params – Dictionary containing ssl parameters to parse to SSLSocket. If None, default ones will be used.

  • no_logs – Whether to disable logging.

  • workers – Number of workers to use. None will disable workers.

  • force_worker_processes –

    Determines whether to use worker processes instead of the default worker threads. By default, when workers is greater than 1, the server will use worker threads. Threads avoid cross-process synchronization issues—such as component registry mismatches (e.g., issues with Lively components) that occur when state lives in separate processes.

    Set this flag to True only when process isolation is explicitly desired and you do not require shared in-memory synchronization between workers.

async async_handle_request_data(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], request_data: duck.http.request_data.RequestData) → None

Processes and handles the request asynchronously.

Parameters:

  • sock – The target client socket.

  • addr – The client address and port.

  • request_data – The full request data object.

handle_request_data(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], request_data: duck.http.request_data.RequestData) → None

Processes and handles the request.

Parameters:

  • sock – The target client socket.

  • addr – The client address and port.

  • request_data – The full request data object.

set_microapp(microapp)

Sets the target micro application for this server instance.

class duck.http.core.httpd.httpd.BaseServer(addr: Tuple[str, int], application: Union[duck.app.app.App, duck.app.microapp.MicroApp], domain: str = None, uses_ipv6: bool = False, enable_ssl: bool = False, ssl_params: Optional[Dict] = None, no_logs: bool = False, workers: Optional[int] = None, force_worker_processes: bool = False)

Base server class containing core server definitions and behaviors.

Features:

  • HTTP Keep-Alive support for persistent connections.

  • Support for incoming requests using chunked Transfer-Encoding.

  • Synchronous + Asynchronous request handling using WSGI or ASGI.’

Request Flow:

  1. start_server is called.

  2. accept_and_handle is called next.

  3. handle_conn is called - Full request is received here.

  4. process_data is then called - RequestData instance is processed, there is proper socket closure here.

  5. handle_request_data is then called last - The RequestData instance is processed further. This func is called by process_data and no socket closure is done here.

Initialization

Initialise the server instance.

Parameters:

  • addr – Tuple of address and port.

  • application – The application that is using this server. Can be either duck main app or micro app.

  • domain – The server domain.

  • uses_ipv6 – Whether If the server is on (IPV6)

  • enable_ssl – Whether to enable HTTPS.

  • ssl_params – Dictionary containing ssl parameters to parse to SSLSocket. If None, default ones will be used.

  • no_logs – Whether to disable logging.

  • workers – Number of workers to use. None will disable workers.

  • force_worker_processes –

    Determines whether to use worker processes instead of the default worker threads. By default, when workers is greater than 1, the server will use worker threads. Threads avoid cross-process synchronization issues—such as component registry mismatches (e.g., issues with Lively components) that occur when state lives in separate processes.

    Set this flag to True only when process isolation is explicitly desired and you do not require shared in-memory synchronization between workers.

accept_and_handle() → socket.socket

Accepts and handle IPV4/IPV6 connection.

Returns:

The client socket instance.

Return type:

xsocket

async async_do_request_timeout(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int])

Sends request timeout response to client and close connection asynchronously.

Parameters:

  • sock – Client socket object

  • addr – Client ip address and port.

async async_handle_conn(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], flowinfo: Optional = None, scopeid: Optional = None) → None

Main entry point to handle new connection asynchronously (supports both ipv6 and ipv4).

Parameters:

  • sock – The client socket object.

  • addr – Client ip address and port.

  • flowinfo – Flow info if IPv6.

  • scopeid – Scope id if IPv6.

async async_handle_keep_alive_conn(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int]) → None

Processes and handles keep alive connection asynchronously.

async async_handle_request_data(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], request_data: duck.http.request_data.RequestData) → None

Asynchronously processes the request using WSGI application callable.

Parameters:

  • sock – Client Socket object

  • addr – Tuple for ip and port from where this request is coming from, ie Client addr

  • request_data – The request data object

async async_process_data(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], request_data: duck.http.request_data.RequestData) → None

Process and handle the request dynamically and asynchronously.

do_request_timeout(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int])

Sends request timeout response to client and close connection.

Parameters:

  • sock – Client socket object

  • addr – Client ip address and port.

handle_conn(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], flowinfo: Optional = None, scopeid: Optional = None) → None

Main entry point to handle new connection (supports both ipv6 and ipv4).

Parameters:

  • sock – The client socket object.

  • addr – Client ip address and port.

  • flowinfo – Flow info if IPv6.

  • scopeid – Scope id if IPv6.

handle_keep_alive_conn(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int]) → None

Processes and handles keep alive connection.

handle_request_data(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], request_data: duck.http.request_data.RequestData) → None

This processes the request using WSGI application callable.

Parameters:

  • sock – Client Socket object

  • addr – Tuple for ip and port from where this request is coming from, ie Client addr

  • request_data – The request data object

process_data(sock: duck.utils.xsocket.xsocket, addr: Tuple[str, int], request_data: duck.http.request_data.RequestData) → None

Process and handle the request dynamically.

property running
property sock
start_server(on_server_start_fn: Optional[Callable] = None)

Starts the HTTP(S) server and begins handling requests.

Parameters:

on_server_start_fn – Function or callable to execute soon after server bind and listen.

start_server_loop(interval_fn: Optional[Callable] = None)

Listen and accept connections.

Parameters:

interval_fn – Function to call before each cycle in the loop.

Notes:

  • self.running must be True.

stop_server(log_to_console: bool = True, wait: bool = True)

Stops the http(s) server.

Parameters:

  • log_to_console – Log the message that the sever stoped. Defaults to True.

  • wait – Wait for worker processes/threads to finish. Defaults to True.

property worker_processes: List[multiprocessing.Process]

Returns list of worker processes.

property worker_threads: List[threading.Thread]

Returns list of worker threads.

duck.http.core.httpd.httpd.CONNECTION_MODE

None

duck.http.core.httpd.httpd.KEEP_ALIVE_PATTERN

‘compile(…)’

duck.http.core.httpd.httpd.KEEP_ALIVE_TIMEOUT

None

duck.http.core.httpd.httpd.SSL_HANDSHAKE_TIMEOUT

0.3

duck.http.core.httpd.httpd.call_request_handling_executor(task: Union[Callable, Coroutine])

This calls the request handling executor with the provided task (thread or coroutine) and the request handling executor keyword arguments set in settings.py.