# `http_multipart`

This library provides a higher-level multipart helper layer on top of the `http_core` library. It does not replace the low-level multipart wire support already implemented in `http_core`; instead it wraps the normalized multipart body and part terms, adds form-data field and file helpers, and delegates raw parsing and generation to the existing `http_core` predicates.

## API documentation

Open the ../../apis/library_index.html#http_multipart link in a web browser.

## Loading

To load the library, load the `loader.lgt` file:

    | ?- logtalk_load(http_multipart(loader)).

## Testing

To test this library, load the `tester.lgt` file:

    | ?- logtalk_load(http_multipart(tester)).

## Current scope

The current version provides:

- `body/3` for constructing validated normalized multipart body terms.

- `part/4` for constructing validated normalized multipart part terms.

- `is_body/1` and `is_part/1` for testing normalized multipart body and part terms.

- `media_type/2` and `parts/2` for inspecting multipart body terms.

- `part_headers/2`, `part_body/2`, and `part_properties/2` for inspecting multipart part terms.

- `field/4` and `fields/2` for inspecting textual form-data field parts and multipart/form-data bodies.

- `file/6` and `files/2` for inspecting form-data file parts and multipart/form-data bodies.

- `field_part/4` and `file_part/6` for constructing outgoing form-data field and file parts.

- `form_data_body/2` for constructing a `multipart/form-data` body from an ordered list of parameter-aware field and file descriptors.

- `parse/4` and `generate/3` as multipart-specific wrappers around the existing `http_core::parse_body/4` and `http_core::generate_body/3` predicates.

## Form-data descriptors

The parameter-aware helper predicates use the following descriptor shapes:

- `field(Name, Value, Parameters)`

- `file(Name, Filename, MediaType, Payload, Parameters)`

In both cases, `Parameters` is an ordered list of extra `Content-Disposition: form-data` parameters represented as `Name-Value` pairs. The reserved `name` and `filename` parameters remain explicit helper arguments and must not be repeated in the `Parameters` list.

Additional `Content-Disposition: form-data` parameters are preserved as ordered `Name-Value` pairs. Any special semantics for extended parameters such as `filename*` are intentionally left to callers.

## Normalized terms

Multipart bodies use the normalized `http_core` body term:

    content(MediaType, multipart(Parts))

Multipart parts use the recursive normalized term:

    part(Headers, Body, Properties)

## Current workflow

- Use `form_data_body/2` when you want to assemble a normalized `multipart/form-data` body explicitly.

- Use the `field/4`, `fields/2`, `file/6`, and `files/2` predicates when you want to inspect multipart form-data bodies after parsing.

- The `http_client` library can send common form-data requests directly from a `form_data(Items)` descriptor.

- The `http_server_core` library keeps multipart request bodies in the normalized form expected by this library, so handlers can inspect incoming multipart requests without reparsing them.

## Current limitations

- The library is entirely in-memory.

- Textual field helpers target simple text field payloads. If a part has a non-text body or a more specialized encoding, callers should use the generic part accessors instead.

- Multipart wire parsing and generation require a boundary parameter in the effective `Content-Type` metadata or an explicit `boundary/1` option, exactly as in the underlying `http_core` library.

- The library does not provide streaming sinks, temp-file policies, or large-upload orchestration.