.. index:: single: http_core
.. _http_core/0:

.. rst-class:: right

**object**

``http_core``
=============

Transport-independent normalized HTTP request and response constructors, validators, wire parsers and generators, and body codec dispatch.

| **Availability:** 
|    ``logtalk_load(http_core(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-07-07

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Imports:**
|    ``public`` :ref:`http_text_helpers <http_text_helpers/0>`
| **Uses:**
|    :ref:`base64 <base64/0>`
|    :ref:`http_cookies(Representation) <http_cookies/1>`
|    :ref:`json <json/0>`
|    :ref:`list <list/0>`
|    :ref:`reader <reader/0>`
|    :ref:`url(Representation) <url/1>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: request/7
.. _http_core/0::request/7:

``request/7``
^^^^^^^^^^^^^

Constructs a validated normalized ``request/6`` term from the given method, target, version, headers, body, and properties.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``request(Method,Target,Version,Headers,Body,Properties,Request)``
| **Mode and number of proofs:**
|    ``request(+atom,+compound,+compound,+list(compound),+compound,+list(compound),-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Method`` is not a valid HTTP method atom:
|        ``domain_error(http_method,Method)``
|    ``Target`` is not a valid normalized HTTP target term:
|        ``domain_error(http_target,Target)``
|    ``Version`` is not a valid HTTP version term:
|        ``domain_error(http_version,Version)``
|    ``Headers`` is not a valid normalized HTTP header list:
|        ``domain_error(http_headers,Headers)``
|    ``Body`` is not a valid normalized HTTP body term:
|        ``domain_error(http_body,Body)``
|    ``Properties`` is not a valid normalized HTTP property list:
|        ``domain_error(http_properties,Properties)``
|    The request headers violate normalized HTTP request semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The request properties violate normalized HTTP request semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: response/6
.. _http_core/0::response/6:

``response/6``
^^^^^^^^^^^^^^

Constructs a validated normalized ``response/5`` term from the given version, status, headers, body, and properties.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``response(Version,Status,Headers,Body,Properties,Response)``
| **Mode and number of proofs:**
|    ``response(+compound,+compound,+list(compound),+compound,+list(compound),-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Version`` is not a valid HTTP version term:
|        ``domain_error(http_version,Version)``
|    ``Status`` is not a valid normalized HTTP status term:
|        ``domain_error(http_status,Status)``
|    ``Headers`` is not a valid normalized HTTP header list:
|        ``domain_error(http_headers,Headers)``
|    ``Body`` is not a valid normalized HTTP body term:
|        ``domain_error(http_body,Body)``
|    ``Properties`` is not a valid normalized HTTP property list:
|        ``domain_error(http_properties,Properties)``
|    The response headers violate normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The response properties violate normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: is_request/1
.. _http_core/0::is_request/1:

``is_request/1``
^^^^^^^^^^^^^^^^

Succeeds if the given term is a structurally and semantically valid normalized ``request/6`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``is_request(Request)``
| **Mode and number of proofs:**
|    ``is_request(+term)`` - ``zero_or_one``


------------

.. index:: is_response/1
.. _http_core/0::is_response/1:

``is_response/1``
^^^^^^^^^^^^^^^^^

Succeeds if the given term is a structurally and semantically valid normalized ``response/5`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``is_response(Response)``
| **Mode and number of proofs:**
|    ``is_response(+term)`` - ``zero_or_one``


------------

.. index:: parse_request/2
.. _http_core/0::parse_request/2:

``parse_request/2``
^^^^^^^^^^^^^^^^^^^

Parses a complete HTTP request message from the given source (``bytes(List)``, ``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) into a normalized ``request/6`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_request(Source,Request)``
| **Mode and number of proofs:**
|    ``parse_request(++compound,--compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid HTTP source term:
|        ``domain_error(http_source,Source)``
|    The parsed request method is not a valid HTTP method atom:
|        ``domain_error(http_method,Method)``
|    The parsed request target is not a valid normalized HTTP target term:
|        ``domain_error(http_target,Target)``
|    The parsed request version is not a valid HTTP version term:
|        ``domain_error(http_version,Version)``
|    The parsed request headers are not a valid normalized HTTP header list:
|        ``domain_error(http_headers,Headers)``
|    The parsed request body is not a valid normalized HTTP body term:
|        ``domain_error(http_body,Body)``
|    The parsed request properties are not a valid normalized HTTP property list:
|        ``domain_error(http_properties,Properties)``
|    The parsed request headers violate normalized HTTP request semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The parsed request properties violate normalized HTTP request semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: generate_request/2
.. _http_core/0::generate_request/2:

``generate_request/2``
^^^^^^^^^^^^^^^^^^^^^^

Generates a complete HTTP request message to the given sink (``bytes(List)``, ``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) from a normalized ``request/6`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_request(Sink,Request)``
| **Mode and number of proofs:**
|    ``generate_request(+compound,++compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid HTTP sink term:
|        ``domain_error(http_sink,Sink)``
|    ``Request`` is not a valid normalized HTTP request term:
|        ``domain_error(http_request,Request)``


------------

.. index:: parse_response/2
.. _http_core/0::parse_response/2:

``parse_response/2``
^^^^^^^^^^^^^^^^^^^^

Parses a complete HTTP response message from the given source (``bytes(List)``, ``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) into a normalized ``response/5`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_response(Source,Response)``
| **Mode and number of proofs:**
|    ``parse_response(++compound,--compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid HTTP source term:
|        ``domain_error(http_source,Source)``
|    The parsed response version is not a valid HTTP version term:
|        ``domain_error(http_version,Version)``
|    The parsed response status is not a valid normalized HTTP status term:
|        ``domain_error(http_status,Status)``
|    The parsed response headers are not a valid normalized HTTP header list:
|        ``domain_error(http_headers,Headers)``
|    The parsed response body is not a valid normalized HTTP body term:
|        ``domain_error(http_body,Body)``
|    The parsed response properties are not a valid normalized HTTP property list:
|        ``domain_error(http_properties,Properties)``
|    The parsed response headers violate normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The parsed response properties violate normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: generate_response/2
.. _http_core/0::generate_response/2:

``generate_response/2``
^^^^^^^^^^^^^^^^^^^^^^^

Generates a complete HTTP response message to the given sink (``bytes(List)``, ``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) from a normalized ``response/5`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_response(Sink,Response)``
| **Mode and number of proofs:**
|    ``generate_response(+compound,++compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid HTTP sink term:
|        ``domain_error(http_sink,Sink)``
|    ``Response`` is not a valid normalized HTTP response term:
|        ``domain_error(http_response,Response)``


------------

.. index:: generate_response_headers/2
.. _http_core/0::generate_response_headers/2:

``generate_response_headers/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates an HTTP response status line and effective header block, terminated by an empty line, to the given sink from a normalized ``response/5`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_response_headers(Sink,Response)``
| **Mode and number of proofs:**
|    ``generate_response_headers(+compound,++compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid HTTP sink term:
|        ``domain_error(http_sink,Sink)``
|    ``Response`` is not a valid normalized HTTP response term:
|        ``domain_error(http_response,Response)``


------------

.. index:: parse_request_line/2
.. _http_core/0::parse_request_line/2:

``parse_request_line/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Parses an HTTP request line from the given source (``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) into a ``request_line(Method, Target, Version)`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_request_line(Source,RequestLine)``
| **Mode and number of proofs:**
|    ``parse_request_line(++compound,--compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid HTTP source term:
|        ``domain_error(http_source,Source)``


------------

.. index:: generate_request_line/2
.. _http_core/0::generate_request_line/2:

``generate_request_line/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates an HTTP request line to the given sink (``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) from a ``request_line(Method, Target, Version)`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_request_line(Sink,RequestLine)``
| **Mode and number of proofs:**
|    ``generate_request_line(+compound,++compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid HTTP sink term:
|        ``domain_error(http_sink,Sink)``


------------

.. index:: parse_status_line/2
.. _http_core/0::parse_status_line/2:

``parse_status_line/2``
^^^^^^^^^^^^^^^^^^^^^^^

Parses an HTTP status line from the given source (``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) into a ``status_line(Version, Status)`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_status_line(Source,StatusLine)``
| **Mode and number of proofs:**
|    ``parse_status_line(++compound,--compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid HTTP source term:
|        ``domain_error(http_source,Source)``


------------

.. index:: generate_status_line/2
.. _http_core/0::generate_status_line/2:

``generate_status_line/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates an HTTP status line to the given sink (``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) from a ``status_line(Version, Status)`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_status_line(Sink,StatusLine)``
| **Mode and number of proofs:**
|    ``generate_status_line(+compound,++compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid HTTP sink term:
|        ``domain_error(http_sink,Sink)``


------------

.. index:: parse_headers/2
.. _http_core/0::parse_headers/2:

``parse_headers/2``
^^^^^^^^^^^^^^^^^^^

Parses an HTTP header block from the given source (``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) into normalized header ``Name-Value`` pairs with typed values for recognized headers.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_headers(Source,Headers)``
| **Mode and number of proofs:**
|    ``parse_headers(++compound,-list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid HTTP source term:
|        ``domain_error(http_source,Source)``


------------

.. index:: generate_headers/2
.. _http_core/0::generate_headers/2:

``generate_headers/2``
^^^^^^^^^^^^^^^^^^^^^^

Generates an HTTP header block to the given sink (``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) from normalized header ``Name-Value`` pairs.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_headers(Sink,Headers)``
| **Mode and number of proofs:**
|    ``generate_headers(+compound,++list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid HTTP sink term:
|        ``domain_error(http_sink,Sink)``
|    ``Headers`` is not a valid normalized HTTP header list:
|        ``domain_error(http_headers,Headers)``


------------

.. index:: parse_body/4
.. _http_core/0::parse_body/4:

``parse_body/4``
^^^^^^^^^^^^^^^^

Parses a body payload from the given source (``bytes(List)``, ``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) according to the given media type and options into a normalized body term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_body(Source,MediaType,Options,Body)``
| **Mode and number of proofs:**
|    ``parse_body(++compound,++atom,+list(compound),--compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid HTTP source term:
|        ``domain_error(http_source,Source)``
|    ``MediaType`` is not a valid HTTP media type atom:
|        ``domain_error(http_media_type,MediaType)``
|    ``Options`` is not a valid HTTP body options list:
|        ``domain_error(http_body_options,Options)``
|    No registered HTTP body codec exists for ``MediaType`` when codec-based decoding is required:
|        ``existence_error(http_body_codec,MediaType)``


------------

.. index:: generate_body/3
.. _http_core/0::generate_body/3:

``generate_body/3``
^^^^^^^^^^^^^^^^^^^

Generates a body payload to the given sink (``bytes(List)``, ``codes(List)``, ``chars(List)``, ``atom(Atom)``, ``file(Path)``, or ``stream(Stream)``) from a normalized body term and options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_body(Sink,Body,Options)``
| **Mode and number of proofs:**
|    ``generate_body(+compound,++compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid HTTP sink term:
|        ``domain_error(http_sink,Sink)``
|    ``Body`` is not a valid normalized HTTP body term:
|        ``domain_error(http_body,Body)``
|    ``Options`` is not a valid HTTP body options list:
|        ``domain_error(http_body_options,Options)``
|    No registered HTTP body codec exists for the body media type when codec-based encoding is required:
|        ``existence_error(http_body_codec,MediaType)``


------------

.. index:: request_body_bytes/4
.. _http_core/0::request_body_bytes/4:

``request_body_bytes/4``
^^^^^^^^^^^^^^^^^^^^^^^^

Generates the transfer-decoded entity-body bytes for a normalized HTTP request body using the request headers and properties to select body serialization options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``request_body_bytes(Headers,Body,Properties,Bytes)``
| **Mode and number of proofs:**
|    ``request_body_bytes(+list(compound),++compound,+list(compound),--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Headers`` is not a valid normalized HTTP header list:
|        ``domain_error(http_headers,Headers)``
|    ``Body`` is not a valid normalized HTTP body term:
|        ``domain_error(http_body,Body)``
|    ``Properties`` is not a valid normalized HTTP property list:
|        ``domain_error(http_properties,Properties)``


------------

.. index:: response_body_bytes/4
.. _http_core/0::response_body_bytes/4:

``response_body_bytes/4``
^^^^^^^^^^^^^^^^^^^^^^^^^

Generates the transfer-decoded entity-body bytes for a normalized HTTP response body using the response headers and properties to select body serialization options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``response_body_bytes(Headers,Body,Properties,Bytes)``
| **Mode and number of proofs:**
|    ``response_body_bytes(+list(compound),++compound,+list(compound),--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Headers`` is not a valid normalized HTTP header list:
|        ``domain_error(http_headers,Headers)``
|    ``Body`` is not a valid normalized HTTP body term:
|        ``domain_error(http_body,Body)``
|    ``Properties`` is not a valid normalized HTTP property list:
|        ``domain_error(http_properties,Properties)``


------------

.. index:: encode_body/4
.. _http_core/0::encode_body/4:

``encode_body/4``
^^^^^^^^^^^^^^^^^

Encodes a semantic payload term using the registered concrete body codec for the given media type into a normalized body term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``encode_body(MediaType,Payload,Options,Body)``
| **Mode and number of proofs:**
|    ``encode_body(+atom,++term,+list(compound),-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``MediaType`` is not a valid HTTP media type atom:
|        ``domain_error(http_media_type,MediaType)``
|    ``Options`` is not a valid HTTP body options list:
|        ``domain_error(http_body_options,Options)``
|    No registered HTTP body codec exists for ``MediaType``:
|        ``existence_error(http_body_codec,MediaType)``


------------

.. index:: decode_body/4
.. _http_core/0::decode_body/4:

``decode_body/4``
^^^^^^^^^^^^^^^^^

Decodes a normalized body term using the registered concrete body codec for the given media type into a semantic payload term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``decode_body(MediaType,Body,Options,Payload)``
| **Mode and number of proofs:**
|    ``decode_body(+atom,++compound,+list(compound),--term)`` - ``one_or_error``

| **Exceptions:**
|    ``MediaType`` is not a valid HTTP media type atom:
|        ``domain_error(http_media_type,MediaType)``
|    ``Options`` is not a valid HTTP body options list:
|        ``domain_error(http_body_options,Options)``
|    No registered HTTP body codec exists for ``MediaType``:
|        ``existence_error(http_body_codec,MediaType)``


------------

.. index:: method/2
.. _http_core/0::method/2:

``method/2``
^^^^^^^^^^^^

Returns the request method from a normalized ``request/6`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``method(Request,Method)``
| **Mode and number of proofs:**
|    ``method(+compound,-atom)`` - ``one_or_error``

| **Exceptions:**


------------

.. index:: target/2
.. _http_core/0::target/2:

``target/2``
^^^^^^^^^^^^

Returns the request target from a normalized ``request/6`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``target(Request,Target)``
| **Mode and number of proofs:**
|    ``target(+compound,-compound)`` - ``one_or_error``

| **Exceptions:**


------------

.. index:: version/2
.. _http_core/0::version/2:

``version/2``
^^^^^^^^^^^^^

Returns the HTTP version from a normalized request or response term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``version(Message,Version)``
| **Mode and number of proofs:**
|    ``version(+compound,-compound)`` - ``one_or_error``

| **Exceptions:**


------------

.. index:: status/2
.. _http_core/0::status/2:

``status/2``
^^^^^^^^^^^^

Returns the response status from a normalized ``response/5`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``status(Response,Status)``
| **Mode and number of proofs:**
|    ``status(+compound,-compound)`` - ``one_or_error``

| **Exceptions:**


------------

.. index:: headers/2
.. _http_core/0::headers/2:

``headers/2``
^^^^^^^^^^^^^

Returns the normalized header list from a request or response term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``headers(Message,Headers)``
| **Mode and number of proofs:**
|    ``headers(+compound,-list(compound))`` - ``one_or_error``

| **Exceptions:**


------------

.. index:: header/3
.. _http_core/0::header/3:

``header/3``
^^^^^^^^^^^^

Enumerates normalized header ``Name`` and ``Value`` pairs from a request or response term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``header(Message,Name,Value)``
| **Mode and number of proofs:**
|    ``header(+compound,?atom,?term)`` - ``zero_or_more``


------------

.. index:: body/2
.. _http_core/0::body/2:

``body/2``
^^^^^^^^^^

Returns the normalized body term from a request or response term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``body(Message,Body)``
| **Mode and number of proofs:**
|    ``body(+compound,-compound)`` - ``one_or_error``

| **Exceptions:**


------------

.. index:: property/2
.. _http_core/0::property/2:

``property/2``
^^^^^^^^^^^^^^

Enumerates normalized derived or higher-layer properties from a request or response term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``property(Message,Property)``
| **Mode and number of proofs:**
|    ``property(+compound,?compound)`` - ``zero_or_more``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)