.. index:: single: s3_protocol .. _s3_protocol/0:

.. rst-class:: right

protocol

s3_protocol

S3-compatible client facade predicates.

| Availability: | logtalk_load(s3(loader))

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

| Compilation flags: | static

| Dependencies: | (none)

| Remarks: | (none)

| Inherited public predicates: | (none)

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

Public predicates

.. index:: list_buckets/2 .. _s3_protocol/0::list_buckets/2:

list_buckets/2 ^^^^^^^^^^^^^^^^^^

Lists accessible buckets.

| Compilation flags: | static

| Template: | list_buckets(Buckets,Options) | Mode and number of proofs: | list_buckets(-compound,+list(compound)) - 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) | Options contains an invalid S3 client option: | domain_error(s3_client_option,Option) | Credentials are missing or invalid: | domain_error(s3_credentials,missing) | The S3 service returned a non-success status or malformed XML body: | domain_error(s3_http_status,Status)

| Remarks:

• Option credentials/1: Required 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. Defaults to us-east-1.
• Option endpoint/1: Optional custom S3-compatible endpoint URL.
• Option addressing_style/1: Endpoint addressing style, either virtual_hosted or path. Defaults to virtual_hosted.
• Option headers/1: Optional extra normalized HTTP request headers.
• Option version/1: HTTP protocol version as http(Major, Minor). Defaults to http(1,1).
• 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. Defaults to signed.
• 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. Defaults to 0.
• Option amz_date/1: Optional explicit AWS SigV4 timestamp overriding any derived request time.

---

.. index:: head_bucket/3 .. _s3_protocol/0::head_bucket/3:

head_bucket/3 ^^^^^^^^^^^^^^^^^

Returns response metadata for a bucket.

| Compilation flags: | static

| Template: | head_bucket(Bucket,Metadata,Options) | Mode and number of proofs: | head_bucket(+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | 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) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | The S3 service returned a non-success status: | domain_error(s3_http_status,Status)

| Remarks:

• Options: Supported options are the standard S3 request options: credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey)), optional session_token(Token), region(Region), optional custom endpoint(URL), addressing_style(virtual_hosted|path), optional headers(Headers), version(http(Major, Minor)), optional properties(Properties), optional connection_options(ConnectionOptions), payload_hash_mode(signed|unsigned), optional request_time(date_time(...)), utc_offset_seconds(OffsetSeconds), and optional explicit amz_date(AmzDate).

---

.. index:: list_objects_v2/4 .. _s3_protocol/0::list_objects_v2/4:

list_objects_v2/4 ^^^^^^^^^^^^^^^^^^^^^

Lists bucket objects using the ListObjectsV2 API.

| Compilation flags: | static

| Template: | list_objects_v2(Bucket,Request,Listing,Options) | Mode and number of proofs: | list_objects_v2(+atom,+compound,-compound,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Request is a variable: | instantiation_error | An element Option of the request option list is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | An element Option of the request option list is neither a variable nor a compound term: | type_error(compound,Option) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | 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) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | The S3 service returned a non-success status or malformed XML body: | domain_error(s3_http_status,Status)

| Remarks:

• Options: Options accepts the standard S3 request options: credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey)), optional session_token(Token), region(Region), optional custom endpoint(URL), addressing_style(virtual_hosted|path), optional headers(Headers), version(http(Major, Minor)), optional properties(Properties), optional connection_options(ConnectionOptions), payload_hash_mode(signed|unsigned), optional request_time(date_time(...)), utc_offset_seconds(OffsetSeconds), and optional explicit amz_date(AmzDate). The Request argument carries the ListObjectsV2-specific request options.

---

.. index:: head_object/4 .. _s3_protocol/0::head_object/4:

head_object/4 ^^^^^^^^^^^^^^^^^

Returns response metadata for an object.

| Compilation flags: | static

| Template: | head_object(Bucket,Key,Metadata,Options) | Mode and number of proofs: | head_object(+atom,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Key is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | Key is neither a variable nor an atom: | type_error(atom,Key) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | The S3 service returned a non-success status: | domain_error(s3_http_status,Status)

| Remarks:

• Options: Supported options are the standard S3 request options: credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey)), optional session_token(Token), region(Region), optional custom endpoint(URL), addressing_style(virtual_hosted|path), optional headers(Headers), version(http(Major, Minor)), optional properties(Properties), optional connection_options(ConnectionOptions), payload_hash_mode(signed|unsigned), optional request_time(date_time(...)), utc_offset_seconds(OffsetSeconds), and optional explicit amz_date(AmzDate).

---

.. index:: get_object/5 .. _s3_protocol/0::get_object/5:

get_object/5 ^^^^^^^^^^^^^^^^

Fetches an object into a local file path and returns its response metadata as a separate argument.

| Compilation flags: | static

| Template: | get_object(Bucket,Key,File,Properties,Options) | Mode and number of proofs: | get_object(+atom,+atom,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Key is a variable: | instantiation_error | File is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | Key is neither a variable nor an atom: | type_error(atom,Key) | File is neither a variable nor an atom: | type_error(atom,File) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | 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) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | The S3 service returned a non-success status: | domain_error(s3_http_status,Status)

| Remarks:

• Options: Supported options are: credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey)) for access credentials; session_token(Token) for temporary credentials; region(Region) for the AWS region, defaulting to us-east-1 when endpoint/1 is absent; endpoint(URL) for a custom S3-compatible endpoint; addressing_style(virtual_hosted|path) for endpoint addressing, defaulting to virtual_hosted; headers(Headers) for extra normalized request headers; version(http(Major, Minor)) for the HTTP protocol version, defaulting to http(1,1); properties(Properties) for extra normalized HTTP request properties; connection_options(ConnectionOptions) for transport-specific HTTP client options; payload_hash_mode(signed|unsigned) for payload signing, defaulting to signed; request_time(date_time(...)) for an explicit local request time; utc_offset_seconds(OffsetSeconds) for deriving UTC from the local clock, defaulting to 0; and amz_date(AmzDate) for an explicit AWS SigV4 timestamp overriding time derivation.

---

.. index:: put_object/6 .. _s3_protocol/0::put_object/6:

put_object/6 ^^^^^^^^^^^^^^^^

Uploads a local file path and returns the object ETag and response metadata as separate arguments.

| Compilation flags: | static

| Template: | put_object(Bucket,Key,File,ETag,Properties,Options) | Mode and number of proofs: | put_object(+atom,+atom,+atom,-atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Key is a variable: | instantiation_error | File is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | Key is neither a variable nor an atom: | type_error(atom,Key) | File is neither a variable nor an atom: | type_error(atom,File) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | File exists but is not a readable file: | domain_error(file([],[read]),File) | The file File does not exist: | existence_error(file,File) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | The S3 service returned a non-success status: | domain_error(s3_http_status,Status)

| Remarks:

• Options: Supported options are the standard S3 request options: credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey)), optional session_token(Token), region(Region), optional custom endpoint(URL), addressing_style(virtual_hosted|path), optional headers(Headers), version(http(Major, Minor)), optional properties(Properties), optional connection_options(ConnectionOptions), payload_hash_mode(signed|unsigned), optional request_time(date_time(...)), utc_offset_seconds(OffsetSeconds), and optional explicit amz_date(AmzDate).

---

.. index:: delete_object/4 .. _s3_protocol/0::delete_object/4:

delete_object/4 ^^^^^^^^^^^^^^^^^^^

Deletes an object, returning delete_result(Properties).

| Compilation flags: | static

| Template: | delete_object(Bucket,Key,Result,Options) | Mode and number of proofs: | delete_object(+atom,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Key is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | Key is neither a variable nor an atom: | type_error(atom,Key) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | The S3 service returned a non-success status: | domain_error(s3_http_status,Status)

| Remarks:

• Options: Supported options are the standard S3 request options: credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey)), optional session_token(Token), region(Region), optional custom endpoint(URL), addressing_style(virtual_hosted|path), optional headers(Headers), version(http(Major, Minor)), optional properties(Properties), optional connection_options(ConnectionOptions), payload_hash_mode(signed|unsigned), optional request_time(date_time(...)), utc_offset_seconds(OffsetSeconds), and optional explicit amz_date(AmzDate).

---

.. index:: copy_object/5 .. _s3_protocol/0::copy_object/5:

copy_object/5 ^^^^^^^^^^^^^^^^^

Copies an object from a source bucket/key into the destination bucket/key, returning copy_result(ETag, Properties).

| Compilation flags: | static

| Template: | copy_object(Source,Bucket,Key,Result,Options) | Mode and number of proofs: | copy_object(+compound,+atom,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Source is a variable: | instantiation_error | Bucket is a variable: | instantiation_error | Key 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) | Key is neither a variable nor an atom: | type_error(atom,Key) | 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) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | The S3 service returned a non-success status or malformed XML body: | domain_error(s3_http_status,Status)

| Remarks:

• Options: Supported options are the standard S3 request options: credentials(access_key_id(AccessKeyId), secret_access_key(SecretAccessKey)), optional session_token(Token), region(Region), optional custom endpoint(URL), addressing_style(virtual_hosted|path), optional headers(Headers), version(http(Major, Minor)), optional properties(Properties), optional connection_options(ConnectionOptions), payload_hash_mode(signed|unsigned), optional request_time(date_time(...)), utc_offset_seconds(OffsetSeconds), and optional explicit amz_date(AmzDate).

---

.. index:: presigned_get_object/4 .. _s3_protocol/0::presigned_get_object/4:

presigned_get_object/4 ^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates a presigned URL for downloading an object with an external HTTP client.

| Compilation flags: | static

| Template: | presigned_get_object(Bucket,Key,URL,Options) | Mode and number of proofs: | presigned_get_object(+atom,+atom,-atom,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Key is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | Key is neither a variable nor an atom: | type_error(atom,Key) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | Credentials are missing or invalid: | domain_error(s3_credentials,missing) | The expiration is invalid or outside the AWS SigV4 range: | domain_error(s3_presign_expires,Expires) | The payload hash is missing, invalid, or incompatible with unsigned mode: | domain_error(s3_presign_payload_hash,Hash)

| Remarks:

• Option credentials/1: Required 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. Defaults to us-east-1.
• Option endpoint/1: Optional custom S3-compatible endpoint URL.
• Option addressing_style/1: Endpoint addressing style, either virtual_hosted or path. Defaults to virtual_hosted.
• Option headers/1: Optional extra normalized request headers. When present they are signed into the URL and must be reproduced by the eventual caller.
• Option payload_hash_mode/1: Presigned URLs default to payload_hash_mode(unsigned). Use signed together with payload_hash/1 to sign a precomputed payload hash.
• Option payload_hash/1: Precomputed hexadecimal SHA-256 payload hash required when payload_hash_mode(signed) is selected.
• 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. Defaults to 0.
• Option amz_date/1: Optional explicit AWS SigV4 timestamp overriding any derived request time.
• Option expires/1: Presigned URL lifetime in seconds. Defaults to 900 and must not exceed 604800.

---

.. index:: presigned_put_object/4 .. _s3_protocol/0::presigned_put_object/4:

presigned_put_object/4 ^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates a presigned URL for uploading an object with an external HTTP client.

| Compilation flags: | static

| Template: | presigned_put_object(Bucket,Key,URL,Options) | Mode and number of proofs: | presigned_put_object(+atom,+atom,-atom,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Key is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | Key is neither a variable nor an atom: | type_error(atom,Key) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | Credentials are missing or invalid: | domain_error(s3_credentials,missing) | The expiration is invalid or outside the AWS SigV4 range: | domain_error(s3_presign_expires,Expires) | The payload hash is missing, invalid, or incompatible with unsigned mode: | domain_error(s3_presign_payload_hash,Hash)

| Remarks:

• Option credentials/1: Required 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. Defaults to us-east-1.
• Option endpoint/1: Optional custom S3-compatible endpoint URL.
• Option addressing_style/1: Endpoint addressing style, either virtual_hosted or path. Defaults to virtual_hosted.
• Option headers/1: Optional extra normalized request headers. When present they are signed into the URL and must be reproduced by the eventual caller.
• Option payload_hash_mode/1: Presigned URLs default to payload_hash_mode(unsigned). Use signed together with payload_hash/1 to sign a precomputed payload hash.
• Option payload_hash/1: Precomputed hexadecimal SHA-256 payload hash required when payload_hash_mode(signed) is selected.
• 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. Defaults to 0.
• Option amz_date/1: Optional explicit AWS SigV4 timestamp overriding any derived request time.
• Option expires/1: Presigned URL lifetime in seconds. Defaults to 900 and must not exceed 604800.

---

.. index:: presigned_post_object/4 .. _s3_protocol/0::presigned_post_object/4:

presigned_post_object/4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates a presigned URL for a POST request to an object with an external HTTP client.

| Compilation flags: | static

| Template: | presigned_post_object(Bucket,Key,URL,Options) | Mode and number of proofs: | presigned_post_object(+atom,+atom,-atom,+list(compound)) - one_or_error

| Exceptions: | Bucket is a variable: | instantiation_error | Key is a variable: | instantiation_error | Bucket is neither a variable nor an atom: | type_error(atom,Bucket) | Key is neither a variable nor an atom: | type_error(atom,Key) | Bucket is an atom but not a valid S3 bucket: | domain_error(s3_bucket,Bucket) | 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 invalid S3 client option: | domain_error(s3_client_option,Option) | Credentials are missing or invalid: | domain_error(s3_credentials,missing) | The expiration is invalid or outside the AWS SigV4 range: | domain_error(s3_presign_expires,Expires) | The payload hash is missing, invalid, or incompatible with unsigned mode: | domain_error(s3_presign_payload_hash,Hash)

| Remarks:

• Option credentials/1: Required 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. Defaults to us-east-1.
• Option endpoint/1: Optional custom S3-compatible endpoint URL.
• Option addressing_style/1: Endpoint addressing style, either virtual_hosted or path. Defaults to virtual_hosted.
• Option headers/1: Optional extra normalized request headers. When present they are signed into the URL and must be reproduced by the eventual caller.
• Option payload_hash_mode/1: Presigned URLs default to payload_hash_mode(unsigned). Use signed together with payload_hash/1 to sign a precomputed payload hash.
• Option payload_hash/1: Precomputed hexadecimal SHA-256 payload hash required when payload_hash_mode(signed) is selected.
• 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. Defaults to 0.
• Option amz_date/1: Optional explicit AWS SigV4 timestamp overriding any derived request time.
• Option expires/1: Presigned URL lifetime in seconds. Defaults to 900 and must not exceed 604800.

---

Protected predicates

(none)

Private predicates

(none)

Operators

(none)