object

# `s3_session(HTTPTransport)`

- `HTTPTransport` - The object implementing `http_transport_protocol`.

Explicit S3 client sessions carrying default request options.

Availability:
`logtalk_load(s3(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-07-13
Compilation flags:
`static, context_switching_calls`
Imports:
`public` options
Uses:
list
s3_client(HTTPTransport)
url(Representation)
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

### `get_object/6`

Fetches an object into a local file path using session defaults merged with per-call options and returns its response metadata as a separate argument.

Compilation flags:
`static`
Template:
`get_object(Session,Bucket,Key,File,Properties,Options)`
Mode and number of proofs:
`get_object(+compound,+atom,+atom,+atom,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`
`File` exists but is not a writable file:
`domain_error(file([],[write]),File)`
The directory `Directory` exists but is not writable:
`domain_error(directory([write]),Directory)`
The directory `Directory` does not exist:
`existence_error(directory,Directory)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Option precedence: Per-call options are merged before the stored session defaults, so explicit call options take precedence.

> - Option `credentials/1`: Access credentials as `credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey))`.

> - Option `session_token/1`: Optional session token for temporary credentials.

> - Option `region/1`: AWS region to use when `endpoint/1` is absent.

> - Option `endpoint/1`: Optional custom S3-compatible endpoint URL.

> - Option `addressing_style/1`: Endpoint addressing style, either `virtual_hosted` or `path`.

> - Option `headers/1`: Optional extra normalized HTTP request headers.

> - Option `version/1`: HTTP protocol version as `http(Major, Minor)`.

> - Option `properties/1`: Optional extra normalized HTTP request properties.

> - Option `connection_options/1`: Optional transport-specific HTTP client options.

> - Option `payload_hash_mode/1`: Payload signing mode, either `signed` or `unsigned`.

> - Option `request_time/1`: Optional explicit local request time as `date_time(Year, Month, Day, Hours, Minutes, Seconds)`.

> - Option `utc_offset_seconds/1`: UTC offset used to derive the signing time from the local clock.

> - Option `amz_date/1`: Optional explicit AWS SigV4 timestamp overriding any derived request time.

### `open/1`

Opens a new S3 client session with no default options.

Compilation flags:
`static`
Template:
`open(Session)`
Mode and number of proofs:
`open(-compound)` - `one_or_error`
Exceptions:

### `open/2`

Opens a new S3 client session with the given default options.

Compilation flags:
`static`
Template:
`open(Session,Options)`
Mode and number of proofs:
`open(-compound,+list(compound))` - `one_or_error`
Exceptions:
`Options` contains an invalid S3 session option:
`domain_error(option,Option)`
Remarks:

> - Option role: `Options` stores default request options reused by later session calls.

> - Option `credentials/1`: Default access credentials as `credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey))`.

> - Option `session_token/1`: Optional default session token for temporary credentials.

> - Option `region/1`: Default AWS region to use when `endpoint/1` is absent.

> - Option `endpoint/1`: Optional default custom S3-compatible endpoint URL.

> - Option `addressing_style/1`: Default endpoint addressing style, either `virtual_hosted` or `path`.

> - Option `headers/1`: Optional default normalized HTTP request headers.

> - Option `version/1`: Default HTTP protocol version as `http(Major, Minor)`.

> - Option `properties/1`: Optional default normalized HTTP request properties.

> - Option `connection_options/1`: Optional default transport-specific HTTP client options.

> - Option `payload_hash_mode/1`: Default payload signing mode, either `signed` or `unsigned`.

> - Option `request_time/1`: Optional default local request time as `date_time(Year, Month, Day, Hours, Minutes, Seconds)`.

> - Option `utc_offset_seconds/1`: Default UTC offset used to derive the signing time from the local clock.

> - Option `amz_date/1`: Optional default AWS SigV4 timestamp overriding any derived request time.

### `close/1`

Closes a S3 client session.

Compilation flags:
`static`
Template:
`close(Session)`
Mode and number of proofs:
`close(+compound)` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`

### `list_buckets/3`

Lists accessible buckets using session defaults merged with per-call options.

Compilation flags:
`static`
Template:
`list_buckets(Session,Buckets,Options)`
Mode and number of proofs:
`list_buckets(+compound,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Options` contains an invalid S3 session option:
`domain_error(option,Option)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` and are merged before the stored session defaults, so explicit call options take precedence.

### `head_bucket/4`

Returns bucket metadata using session defaults merged with per-call options.

Compilation flags:
`static`
Template:
`head_bucket(Session,Bucket,Metadata,Options)`
Mode and number of proofs:
`head_bucket(+compound,+atom,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` and are merged before the stored session defaults, so explicit call options take precedence.

### `list_objects_v2/5`

Lists objects using session defaults merged with per-call options.

Compilation flags:
`static`
Template:
`list_objects_v2(Session,Bucket,Request,Listing,Options)`
Mode and number of proofs:
`list_objects_v2(+compound,+atom,+compound,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Request` is a variable:
`instantiation_error`
An element `Option` of the request option list is a variable:
`instantiation_error`
An element `Option` of the request option list is neither a variable nor a compound term:
`type_error(compound,Option)`
`Request` is not a valid ListObjectsV2 request term or option list:
`domain_error(s3_list_objects_request,Request)`
An element `Option` of the request option list is a compound term but not a valid ListObjectsV2 request option:
`domain_error(s3_list_objects_request_option,Option)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` and are merged before the stored session defaults, so explicit call options take precedence. The `Request` argument carries the ListObjectsV2-specific request terms.

### `head_object/5`

Returns object metadata using session defaults merged with per-call options.

Compilation flags:
`static`
Template:
`head_object(Session,Bucket,Key,Metadata,Options)`
Mode and number of proofs:
`head_object(+compound,+atom,+atom,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` and are merged before the stored session defaults, so explicit call options take precedence.

### `presigned_get_object/5`

Generates a presigned download URL using session defaults merged with per-call options.

Compilation flags:
`static`
Template:
`presigned_get_object(Session,Bucket,Key,URL,Options)`
Mode and number of proofs:
`presigned_get_object(+compound,+atom,+atom,-atom,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
The delegated S3 client request failed:
`domain_error(s3_client_option,Option)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` plus `expires(Seconds)` for the URL lifetime and `payload_hash(Hash)` when `payload_hash_mode(signed)` is selected. Presigned URLs default to `payload_hash_mode(unsigned)`. Options are merged before the stored session defaults, so explicit call options take precedence.

### `presigned_put_object/5`

Generates a presigned upload URL using session defaults merged with per-call options.

Compilation flags:
`static`
Template:
`presigned_put_object(Session,Bucket,Key,URL,Options)`
Mode and number of proofs:
`presigned_put_object(+compound,+atom,+atom,-atom,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
The delegated S3 client request failed:
`domain_error(s3_client_option,Option)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` plus `expires(Seconds)` for the URL lifetime and `payload_hash(Hash)` when `payload_hash_mode(signed)` is selected. Presigned URLs default to `payload_hash_mode(unsigned)`. Options are merged before the stored session defaults, so explicit call options take precedence.

### `presigned_post_object/5`

Generates a presigned POST URL using session defaults merged with per-call options.

Compilation flags:
`static`
Template:
`presigned_post_object(Session,Bucket,Key,URL,Options)`
Mode and number of proofs:
`presigned_post_object(+compound,+atom,+atom,-atom,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
The delegated S3 client request failed:
`domain_error(s3_client_option,Option)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` plus `expires(Seconds)` for the URL lifetime and `payload_hash(Hash)` when `payload_hash_mode(signed)` is selected. Presigned URLs default to `payload_hash_mode(unsigned)`. Options are merged before the stored session defaults, so explicit call options take precedence.

### `put_object/7`

Uploads a local file path using session defaults merged with per-call options and returns the object ETag and response metadata as separate arguments.

Compilation flags:
`static`
Template:
`put_object(Session,Bucket,Key,File,ETag,Properties,Options)`
Mode and number of proofs:
`put_object(+compound,+atom,+atom,+atom,-atom,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`
`File` exists but is not a readable file:
`domain_error(file([],[read]),File)`
The file `File` does not exist:
`existence_error(file,File)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` and are merged before the stored session defaults, so explicit call options take precedence.

### `delete_object/5`

Deletes an object using session defaults merged with per-call options, returning `delete_result(Properties)`.

Compilation flags:
`static`
Template:
`delete_object(Session,Bucket,Key,Result,Options)`
Mode and number of proofs:
`delete_object(+compound,+atom,+atom,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` and are merged before the stored session defaults, so explicit call options take precedence.

### `copy_object/6`

Copies an object using session defaults merged with per-call options, returning `copy_result(ETag, Properties)`.

Compilation flags:
`static`
Template:
`copy_object(Session,Source,Bucket,Key,Result,Options)`
Mode and number of proofs:
`copy_object(+compound,+compound,+atom,+atom,-compound,+list(compound))` - `one_or_error`
Exceptions:
`Session` is a variable:
`instantiation_error`
`Session` is neither a variable nor a valid S3 session handle:
`domain_error(s3_session,Session)`
`Session` is a valid S3 session handle but not open:
`existence_error(s3_session,Session)`
`Bucket` is a variable:
`instantiation_error`
`Source` is a variable:
`instantiation_error`
The version identifier in `Source` is a variable:
`instantiation_error`
`Source` is neither a variable nor a compound term:
`type_error(compound,Source)`
`Bucket` is neither a variable nor an atom:
`type_error(atom,Bucket)`
The version identifier in `Source` is neither a variable nor an atom:
`type_error(atom,VersionId)`
`Source` is a compound term but not a valid copy source term:
`domain_error(s3_copy_source,Source)`
`Bucket` is an atom but not a valid S3 bucket:
`domain_error(s3_bucket,Bucket)`
The version identifier in `Source` is an atom but not a valid version identifier:
`domain_error(s3_version_id,VersionId)`
`Key` is a variable:
`instantiation_error`
`Key` is neither a variable nor an atom:
`type_error(atom,Key)`
The delegated S3 client request failed:
`domain_error(s3_http_status,Status)`
Remarks:

> - Options: Per-call options accept the same terms as `open/2` and are merged before the stored session defaults, so explicit call options take precedence.

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

### `session_seed_/1`

Dynamic counter used to generate fresh session identifiers.

Compilation flags:
`dynamic`
Template:
`session_seed_(SessionId)`
Mode and number of proofs:
`session_seed_(?positive_integer)` - `zero_or_one`

### `session_state_/2`

Dynamic mapping between session identifiers and their stored default option lists.

Compilation flags:
`dynamic`
Template:
`session_state_(SessionId,Options)`
Mode and number of proofs:
`session_state_(?positive_integer,?list(compound))` - `zero_or_more`

## Operators

(none)