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)