object

# `http_server`

User-facing HTTP(S) server facade built on top of the HTTP transport libraries.

Availability:
`logtalk_load(http_server(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-07-13
Compilation flags:
`static, context_switching_calls, threaded`
Imports:
`public` options
Uses:
list
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `open/3`

Opens a listener on the loopback address using the selected scheme and transport options and returns an opaque server handle.

Compilation flags:
`static`
Template:
`open(Port,Server,Options)`
Mode and number of proofs:
`open(+integer,--compound,+list)` - `one_or_error`
Exceptions:
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The selected transport object does not exist:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Port` is not a non-negative integer or a variable accepted by the selected transport:
`domain_error(non_negative_integer,Port)`
`Options` contains listener options rejected by the selected transport:
`domain_error(option,Option)`
The selected transport cannot open the listener:
`resource_error(http_process_transport_listener)`

### `open/4`

Opens a listener on the given host using the selected scheme and transport options and returns an opaque server handle.

Compilation flags:
`static`
Template:
`open(Host,Port,Server,Options)`
Mode and number of proofs:
`open(+atom,+integer,--compound,+list)` - `one_or_error`
Exceptions:
`Host` is not a valid listener host atom for the selected transport:
`type_error(atom,Host)`
`Port` is not a non-negative integer or a variable accepted by the selected transport:
`domain_error(non_negative_integer,Port)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The selected transport object does not exist:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Options` contains listener options rejected by the selected transport:
`domain_error(option,Option)`
The selected transport cannot open the listener:
`resource_error(http_process_transport_listener)`

### `close/1`

Closes an open server listener.

Compilation flags:
`static`
Template:
`close(Server)`
Mode and number of proofs:
`close(+compound)` - `one_or_error`
Exceptions:
`Server` is a variable:
`instantiation_error`
`Server` is not an open HTTP server handle:
`domain_error(http_server,Server)`
`Server` refers to a listener rejected by the selected transport:
`domain_error(http_socket_transport_listener,Listener)`
`Server` refers to a listener that no longer exists for the selected transport:
`existence_error(http_socket_transport_listener,Listener)`

### `request_listener_shutdown/1`

Requests shutdown of a blocking accept operation on an open server listener.

Compilation flags:
`static`
Template:
`request_listener_shutdown(Server)`
Mode and number of proofs:
`request_listener_shutdown(+compound)` - `one_or_error`
Exceptions:
`Server` is a variable:
`instantiation_error`
`Server` is not an HTTP server handle:
`domain_error(http_server,Server)`
`Server` refers to a listener rejected by the selected transport:
`domain_error(http_socket_transport_listener,Listener)`
`Server` refers to a listener that no longer exists for the selected transport:
`existence_error(http_socket_transport_listener,Listener)`

### `serve_once/3`

Serves a single request on an open server listener.

Compilation flags:
`static`
Template:
`serve_once(Server,Handler,ClientInfo)`
Mode and number of proofs:
`serve_once(+compound,+object_identifier,--compound)` - `one_or_error`
Exceptions:
`Server` is a variable:
`instantiation_error`
`Server` is not an open HTTP server handle:
`domain_error(http_server,Server)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`

### `serve_websocket_once/5`

Serves a single WebSocket opening handshake on an open server listener.

Compilation flags:
`static`
Template:
`serve_websocket_once(Server,Handler,Connection,Response,ClientInfo)`
Mode and number of proofs:
`serve_websocket_once(+compound,+object_identifier,--compound,--compound,--compound)` - `one_or_error`
Exceptions:
`Server` is a variable:
`instantiation_error`
`Server` is not an open HTTP server handle:
`domain_error(http_server,Server)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The WebSocket opening request does not exist:
`existence_error(http_socket_transport_websocket_request,end_of_file)`
The WebSocket opening response is invalid:
`domain_error(http_socket_transport_websocket_response,Response)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`

### `serve/4`

Serves a bounded number of requests on an open server, or opens a loopback listener, serves requests, and closes it.

Compilation flags:
`static`
Template:
`serve(ServerOrPort,Handler,Count,ClientInfosOrOptions)`
Mode and number of proofs:
`serve(+compound,+object_identifier,+integer,--list)` - `one_or_error`
`serve(+integer,+object_identifier,+integer,+list)` - `one_or_error`
Exceptions:
`ServerOrPort` is a variable:
`instantiation_error`
`ServerOrPort` is neither a variable nor a compound or integer:
`type_error(atom_or_compound,ServerOrPort)`
`ServerOrPort` is a compound term but not an open HTTP server handle:
`domain_error(http_server,ServerOrPort)`
`Count` is a variable:
`instantiation_error`
`Count` is not a non-negative integer:
`domain_error(non_negative_integer,Count)`
`ClientInfosOrOptions` is a variable when opening a listener from a port:
`instantiation_error`
`ClientInfosOrOptions` is neither a variable nor a list when opening a listener from a port:
`type_error(list,Options)`
An element `Option` of the list `ClientInfosOrOptions` is a variable when opening a listener from a port:
`instantiation_error`
An element `Option` of the list `ClientInfosOrOptions` is neither a variable nor a compound term when opening a listener from a port:
`type_error(compound,Option)`
An element `Option` of the list `ClientInfosOrOptions` is a compound term but not a valid option when opening a listener from a port:
`domain_error(option,Option)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The selected transport object does not exist when opening a listener from a port:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol when opening a listener from a port:
`domain_error(http_transport_protocol_object,Transport)`
`ClientInfosOrOptions` selects incompatible scheme and transport values when opening a listener from a port:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`ClientInfosOrOptions` selects incompatible scheme and listener transport values when opening a listener from a port:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`
Thread workers are not available on this backend:
`resource_error(threads)`

### `serve/5`

Serves a bounded number of requests on an open server, or opens a loopback listener, serves requests, and closes it.

Compilation flags:
`static`
Template:
`serve(ServerOrPort,Handler,Count,ClientInfos,Options)`
Mode and number of proofs:
`serve(+compound,+object_identifier,+integer,--list,+list)` - `one_or_error`
`serve(+integer,+object_identifier,+integer,--list,+list)` - `one_or_error`
Exceptions:
`ServerOrPort` is a variable:
`instantiation_error`
`ServerOrPort` is neither a variable nor a compound or integer:
`type_error(atom_or_compound,ServerOrPort)`
`ServerOrPort` is a compound term but not an open HTTP server handle:
`domain_error(http_server,ServerOrPort)`
`Count` is a variable:
`instantiation_error`
`Count` is not a non-negative integer:
`domain_error(non_negative_integer,Count)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
`Options` contains an option that is not valid for serving on an already open server:
`domain_error(http_server_serve_option,Option)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The selected transport object does not exist when opening a listener from a port:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol when opening a listener from a port:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values when opening a listener from a port:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values when opening a listener from a port:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Options` contains listener-serving options rejected by the selected transport:
`domain_error(http_socket_transport_listener_option,Option)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`
Thread workers are not available on this backend:
`resource_error(threads)`

### `serve/6`

Opens a listener on the given host, serves a bounded number of requests, and closes it.

Compilation flags:
`static`
Template:
`serve(Host,Port,Handler,Count,ClientInfos,Options)`
Mode and number of proofs:
`serve(+atom,+integer,+object_identifier,+integer,--list,+list)` - `one_or_error`
Exceptions:
`Host` is not a valid listener host atom for the selected transport:
`type_error(atom,Host)`
`Port` is not a non-negative integer or a variable accepted by the selected transport:
`domain_error(non_negative_integer,Port)`
`Count` is a variable:
`instantiation_error`
`Count` is not a non-negative integer:
`domain_error(non_negative_integer,Count)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The selected transport object does not exist:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Options` contains listener-serving options rejected by the selected transport:
`domain_error(http_socket_transport_listener_option,Option)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`
Thread workers are not available on this backend:
`resource_error(threads)`
The selected transport cannot open or close the listener:
`resource_error(http_process_transport_listener)`

### `serve_until_shutdown/5`

Opens a listener on the given host and serves requests until shutdown is requested.

Compilation flags:
`static`
Template:
`serve_until_shutdown(Host,Port,Handler,Control,Options)`
Mode and number of proofs:
`serve_until_shutdown(+atom,+integer,+object_identifier,+nonvar,+list)` - `one_or_error`
Exceptions:
`Host` is not a valid listener host atom for the selected transport:
`type_error(atom,Host)`
`Port` is not a non-negative integer or a variable accepted by the selected transport:
`domain_error(non_negative_integer,Port)`
`Control` is a variable:
`instantiation_error`
`Control` is already registered for another open-ended server loop:
`permission_error(open,http_server_shutdown_control,Control)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The selected transport object does not exist:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Options` contains listener-serving options rejected by the selected transport:
`domain_error(http_socket_transport_listener_option,Option)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`
Thread workers are not available on this backend:
`resource_error(threads)`
The selected transport cannot open the listener:
`resource_error(http_process_transport_listener)`

### `serve_until_shutdown/6`

Opens a listener on the given host, calls Ready after shutdown control registration, and serves requests until shutdown is requested.

Compilation flags:
`static`
Template:
`serve_until_shutdown(Host,Port,Handler,Control,Options,Ready)`
Meta-predicate template:
`serve_until_shutdown(*,*,*,*,*,0)`
Mode and number of proofs:
`serve_until_shutdown(+atom,+integer,+object_identifier,+nonvar,+list,+callable)` - `one_or_error`
Exceptions:
`Host` is not a valid listener host atom for the selected transport:
`type_error(atom,Host)`
`Port` is not a non-negative integer or a variable accepted by the selected transport:
`domain_error(non_negative_integer,Port)`
`Control` is a variable:
`instantiation_error`
`Control` is already registered for another open-ended server loop:
`permission_error(open,http_server_shutdown_control,Control)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The selected transport object does not exist:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Options` contains listener-serving options rejected by the selected transport:
`domain_error(http_socket_transport_listener_option,Option)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`
Thread workers are not available on this backend:
`resource_error(threads)`
The selected transport cannot open the listener:
`resource_error(http_process_transport_listener)`

### `request_shutdown/1`

Requests shutdown of an open-ended server loop.

Compilation flags:
`static`
Template:
`request_shutdown(Control)`
Mode and number of proofs:
`request_shutdown(+nonvar)` - `one_or_error`
Exceptions:
`Control` is a variable:
`instantiation_error`
`Control` is not registered for an open-ended server loop:
`existence_error(http_server_shutdown_control,Control)`
Thread-backed shutdown is not available on this backend:
`resource_error(threads)`

### `server_property/2`

Enumerates selected properties of a server handle.

Compilation flags:
`static`
Template:
`server_property(Server,Property)`
Mode and number of proofs:
`server_property(+compound,?compound)` - `zero_or_more`

### `start/4`

Starts an open-ended loopback server in a worker thread and waits until it is ready to accept requests. Throws a resource error when thread support is not available.

Compilation flags:
`static`
Template:
`start(Port,Handler,Server,Options)`
Mode and number of proofs:
`start(+integer,+object_identifier,--compound,+list)` - `one_or_error`
Exceptions:
`Port` is not a non-negative integer or a variable accepted by the selected transport:
`domain_error(non_negative_integer,Port)`
`Options` specifies a variable shutdown control:
`instantiation_error`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The selected transport object does not exist:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Options` contains listener-serving options rejected by the selected transport:
`domain_error(http_socket_transport_listener_option,Option)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`
The selected transport cannot open the listener:
`resource_error(http_process_transport_listener)`
Thread support is not available:
`resource_error(threads)`

### `start/5`

Starts an open-ended server in a worker thread and waits until it is ready to accept requests. Throws a resource error when thread support is not available.

Compilation flags:
`static`
Template:
`start(Host,Port,Handler,Server,Options)`
Mode and number of proofs:
`start(+atom,+integer,+object_identifier,--compound,+list)` - `one_or_error`
Exceptions:
`Host` is not a valid listener host atom for the selected transport:
`type_error(atom,Host)`
`Port` is not a non-negative integer or a variable accepted by the selected transport:
`domain_error(non_negative_integer,Port)`
`Options` specifies a variable shutdown control:
`instantiation_error`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The selected transport object does not exist:
`existence_error(object,Transport)`
The selected transport object does not conform to the HTTP transport protocol:
`domain_error(http_transport_protocol_object,Transport)`
`Options` selects incompatible scheme and transport values:
`consistency_error(http_server_options,scheme(Scheme),transport(Transport))`
`Options` selects incompatible scheme and listener transport values:
`consistency_error(http_server_options,scheme(Scheme),listener_transport(ListenerTransport))`
`Options` contains listener-serving options rejected by the selected transport:
`domain_error(http_socket_transport_listener_option,Option)`
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
The delegated HTTP server rejects the response stream:
`domain_error(http_response_stream,Error)`
The selected transport cannot open the listener:
`resource_error(http_process_transport_listener)`
Thread support is not available:
`resource_error(threads)`

### `stop/1`

Requests shutdown of a threaded server and waits for the worker thread to finish. Throws a resource error when thread support is not available.

Compilation flags:
`static`
Template:
`stop(Server)`
Mode and number of proofs:
`stop(+compound)` - `one_or_error`
Exceptions:
`Server` is a variable:
`instantiation_error`
`Server` is not a threaded HTTP server handle:
`domain_error(http_server,Server)`
Thread support is not available:
`resource_error(threads)`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

### `server_control_/3`

Table of HTTP server shutdown control handles.

Compilation flags:
`dynamic`
Template:
`server_control_(Control,Transport,Server)`
Mode and number of proofs:
`server_control_(?nonvar,?object_identiifer,?compound)` - `zero_or_more`

### `server_control_counter_/1`

Counter for generating unique HTTP server shutdown control identifiers.

Compilation flags:
`dynamic`
Template:
`server_control_counter_(Counter)`
Mode and number of proofs:
`server_control_counter_(-integer)` - `zero_or_one`

## Operators

(none)