object

# `http_server_core`

Portable stream-based HTTP server orchestration predicates.

Availability:
`logtalk_load(http_server_core(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-07-08
Compilation flags:
`static, context_switching_calls`
Imports:
`public` http_message_helpers
Uses:
http_core
http_websocket_handshake
list
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `read_request/2`

Reads exactly one HTTP request from a binary stream and returns it as a normalized request term. Fails on clean end-of-file before reading any bytes.

Compilation flags:
`static`
Template:
`read_request(Input,Request)`
Mode and number of proofs:
`read_request(+stream,--compound)` - `zero_or_one`

### `write_response/2`

Writes exactly one normalized HTTP response term to a binary stream.

Compilation flags:
`static`
Template:
`write_response(Output,Response)`
Mode and number of proofs:
`write_response(+stream,+compound)` - `one_or_error`
Exceptions:
`Output` is invalid for the delegated HTTP response generator:
`domain_error(http_sink,stream(Output))`
`Response` is not a valid normalized HTTP response term:
`domain_error(http_response,Response)`
The response body file range is outside the file contents:
`domain_error(http_body_file_range,file(File,Offset,Length))`

### `dispatch/3`

Dispatches a normalized HTTP request to a handler object implementing the http_handler_protocol protocol. Handler failures, exceptions, or invalid responses are converted to an internal server error response.

Compilation flags:
`static`
Template:
`dispatch(Handler,Request,Response)`
Mode and number of proofs:
`dispatch(+object_identifier,+compound,-compound)` - `one_or_error`
Exceptions:

### `serve/3`

Reads one request from a binary input stream, dispatches it to a handler object, and writes one response to a binary output stream. HEAD requests suppress response body bytes on the wire while preserving the generated response headers. Malformed requests are converted to bad request responses.

Compilation flags:
`static`
Template:
`serve(Input,Output,Handler)`
Mode and number of proofs:
`serve(+stream,+stream,+object_identifier)` - `zero_or_one`

### `serve_connection/3`

Repeatedly reads requests from a binary input stream, dispatches them to a handler object, and writes responses to a binary output stream until end-of-file, a `101 Switching Protocols` response, or connection-close semantics terminate the connection. HEAD requests suppress response body bytes on the wire while preserving the generated response headers.

Compilation flags:
`static`
Template:
`serve_connection(Input,Output,Handler)`
Mode and number of proofs:
`serve_connection(+stream,+stream,+object_identifier)` - `one_or_error`
Exceptions:
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
`Output` is invalid for the delegated HTTP response generator:
`domain_error(http_sink,stream(Output))`
The generated response is not a valid normalized HTTP response term:
`domain_error(http_response,Response)`
The response body file range is outside the file contents:
`domain_error(http_body_file_range,file(File,Offset,Length))`

### `accept_websocket/3`

Validates a normalized WebSocket opening-handshake request and builds a matching `101 Switching Protocols` response. The `protocol(Protocol)` option can be used to select a single offered subprotocol.

Compilation flags:
`static`
Template:
`accept_websocket(Request,Response,Options)`
Mode and number of proofs:
`accept_websocket(+compound,--compound,+list)` - `one_or_error`
Exceptions:
`Options` contains an invalid WebSocket acceptance option:
`domain_error(http_server_core_websocket_option,Option)`
`Options` contains reserved WebSocket handshake headers:
`domain_error(http_server_core_websocket_headers,Headers)`
`Options` contains reserved WebSocket handshake properties:
`domain_error(http_server_core_websocket_properties,Properties)`
`Request` is not a valid normalized WebSocket opening-handshake request:
`domain_error(http_server_core_websocket_request,Request)`
`Options` selects a subprotocol not offered by `Request`:
`domain_error(http_server_core_websocket_protocol,Protocol)`
The generated WebSocket response is not a valid normalized HTTP response term:
`domain_error(http_response,Response)`
Remarks:

> - Repeated options: When the same WebSocket acceptance option is given multiple times, the first occurrence is used.

### `serve_websocket/4`

Reads one request from a binary input stream, dispatches it to a handler object, writes one response to a binary output stream, and returns `accepted(Request, Response)` when the exchange completed with a valid WebSocket opening-handshake response. Malformed requests and non-upgrade responses are written to the stream and reported as `rejected(Response)`. Clean end-of-file before any bytes are read is reported as `end_of_file`.

Compilation flags:
`static`
Template:
`serve_websocket(Input,Output,Handler,Outcome)`
Mode and number of proofs:
`serve_websocket(+stream,+stream,+object_identifier,--compound)` - `one_or_error`
Exceptions:
`Handler` does not conform to the HTTP handler protocol:
`domain_error(http_handler_protocol,Handler)`
`Output` is invalid for the delegated HTTP response generator:
`domain_error(http_sink,stream(Output))`
The generated response is not a valid normalized HTTP response term:
`domain_error(http_response,Response)`
The response body file range is outside the file contents:
`domain_error(http_body_file_range,file(File,Offset,Length))`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)