#s3 API reference

An S3-compatible object-storage client: get / put / delete objects and list a bucket, signing every request with AWS Signature Version 4. The endpoint is configurable, so one module serves AWS S3 and every S3-compatible store (MinIO, Cloudflare R2, Backblaze B2) - a selectable backend, not a module per vendor. Path-style addressing ({endpoint}/{bucket}/{key}). SigV4 is HMAC-SHA256 key-chaining, so this builds on hash.hmac + hash.compute + encoding (hex) + time (the request timestamp) + http. Needs the default jennifer binary (net via http).

Import with import "s3.j" as s3;. See the s3 guide for prose and examples.

#Functions

#s3.abortMultipartUpload(client as Client, bucketName as string, key as string, uploadId as string)

Abort a multipart upload, discarding its uploaded parts (call this on failure so the parts do not linger and accrue storage cost).

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• uploadId {string} - the id from createMultipartUpload

Returns {http.Response} - the response (204 on success)

#s3.completeMultipartUpload(client as Client, bucketName as string, key as string, uploadId as string, etags as list of string)

Complete a multipart upload, assembling the uploaded parts into the final object. etags are the ETags from uploadPart in part-number order (part 1 first).

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• uploadId {string} - the id from createMultipartUpload
• etags {list of string} - the part ETags, in part-number order

Returns {http.Response} - the response (200 with a CompleteMultipartUploadResult body)

#s3.connect(endpoint as string, region as string, accessKey as string, secretKey as string)

Build a client for an S3 endpoint. The endpoint is any S3-compatible base URL (scheme://host[:port], no trailing slash).

Parameters

• endpoint {string} - the base URL
• region {string} - the signing region
• accessKey {string} - the access key id
• secretKey {string} - the secret access key

Returns {Client} - a configured client (30 s timeout; set .timeout to change it)

#s3.copy(client as Client, srcBucket as string, srcKey as string, dstBucket as string, dstKey as string)

Copy an object server-side (no download / re-upload): PUT the destination with an x-amz-copy-source of /{srcBucket}/{srcKey} (signed). Source and destination may share a bucket (a rename when paired with delete).

Parameters

• client {Client} - the client
• srcBucket {string} - the source bucket
• srcKey {string} - the source object key
• dstBucket {string} - the destination bucket
• dstKey {string} - the destination object key

Returns {http.Response} - the response (200 with a CopyObjectResult body on success)

#s3.createMultipartUpload(client as Client, bucketName as string, key as string, contentType as string)

Begin a multipart upload (for objects beyond the ~5 GB single-PUT limit, or to stream parts). Returns the upload id to pass to uploadPart / completeMultipartUpload / abortMultipartUpload.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• contentType {string} - the object content type ("" = default)

Returns {string} - the upload id

Throws

• {Error} - kind "s3" when the response carries no UploadId

#s3.delete(client as Client, bucketName as string, key as string)

DELETE an object.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key

Returns {http.Response} - the response (204 on success)

#s3.get(client as Client, bucketName as string, key as string)

GET an object. The response body is the object's contents; a missing object comes back as a 404 http.Response, not an error.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key

Returns {http.Response} - the response (body = object contents on 200)

#s3.getBytes(client as Client, bucketName as string, key as string)

GET an object as raw bytes (the byte-safe download). Use this for binary objects (images, archives) that a UTF-8 string body cannot hold; get stays the text convenience.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key

Returns {http.BytesResponse} - the response (body = raw object bytes on 200)

#s3.head(client as Client, bucketName as string, key as string)

HEAD an object: its metadata (status + headers) without the body. A present object returns 200 with Content-Length / Content-Type / x-amz-meta-* headers; a missing one returns 404.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key

Returns {http.Response} - the response (headers only, empty body)

#s3.isTruncated(xml as string)

Report whether a ListObjectsV2 XML body was truncated (more pages remain).

Parameters

• xml {string} - the body from a list call

Returns {bool} - true when another page is available

#s3.listObjects(client as Client, bucketName as string)

List a bucket's objects (S3 ListObjectsV2). The response body is the S3 XML listing; pass it to s3.objectKeys to pull out the keys. S3 returns at most 1000 keys per page: check s3.isTruncated on the body and, if true, call s3.listObjectsFrom with s3.nextContinuationToken to fetch the next page (loop until not truncated).

Parameters

• client {Client} - the client
• bucketName {string} - the bucket

Returns {http.Response} - the response (body = ListBucketResult XML on 200)

#s3.listObjectsFrom(client as Client, bucketName as string, token as string)

Fetch one further page of a ListObjectsV2 listing, starting after token (the value from s3.nextContinuationToken on the previous page's body).

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• token {string} - the continuation token from the previous page

Returns {http.Response} - the response (body = ListBucketResult XML on 200)

#s3.nextContinuationToken(xml as string)

Extract the continuation token to fetch the next page, or "" when none.

Parameters

• xml {string} - the body from a list call

Returns {string} - the next continuation token, or "" if the listing is complete

#s3.objectKeys(xml as string)

Extract the object keys from a ListObjectsV2 XML body (the <Key> elements).

Parameters

• xml {string} - the body from s3.listObjects

Returns {list of string} - the object keys, in listing order

#s3.presign(client as Client, method as string, bucketName as string, key as string, expiresSeconds as int)

Build a presigned URL that grants time-limited access to an object without exposing the secret key, using SigV4 query-signing (X-Amz-* query parameters). The URL works from any HTTP client until it expires. Pure (no request is sent), so it runs on both binaries.

Parameters

• client {Client} - the client
• method {string} - the HTTP method the URL authorizes (e.g. "GET", "PUT")
• bucketName {string} - the bucket
• key {string} - the object key
• expiresSeconds {int} - the validity window in seconds (max 604800 = 7 days)

Returns {string} - the presigned URL

#s3.put(client as Client, bucketName as string, key as string, body as string)

PUT (upload / overwrite) an object with the given body.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• body {string} - the object contents

Returns {http.Response} - the response (200 on success)

#s3.putBytes(client as Client, bucketName as string, key as string, data as bytes)

PUT (upload / overwrite) an object from a raw bytes body, written byte-for-byte so a binary payload round-trips intact.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• data {bytes} - the object contents

Returns {http.Response} - the response (200 on success)

#s3.putBytesWith(client as Client, bucketName as string, key as string, data as bytes, contentType as string, metadata as map of string to string)

PUT an object (raw bytes body) with an explicit content type and user metadata - the binary counterpart to putWith.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• data {bytes} - the object contents
• contentType {string} - the object content type ("" = default)
• metadata {map of string to string} - user metadata (stored as x-amz-meta-<key>)

Returns {http.Response} - the response (200 on success)

#s3.putWith(client as Client, bucketName as string, key as string, body as string, contentType as string, metadata as map of string to string)

PUT an object (string body) with an explicit content type and user metadata. The Content-Type and each x-amz-meta-<key> header are part of the signature, so they reach S3 intact. Pass "" for the default content type and {} for no metadata.

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• body {string} - the object contents
• contentType {string} - the object content type (e.g. "text/html"; "" = default)
• metadata {map of string to string} - user metadata (stored as x-amz-meta-<key>)

Returns {http.Response} - the response (200 on success)

#s3.uploadPart(client as Client, bucketName as string, key as string, uploadId as string, partNumber as int, data as bytes)

Upload one part of a multipart upload (each part >= 5 MiB except the last). Returns the part's ETag, which completeMultipartUpload needs (collect them in part-number order).

Parameters

• client {Client} - the client
• bucketName {string} - the bucket
• key {string} - the object key
• uploadId {string} - the id from createMultipartUpload
• partNumber {int} - the 1-based part number
• data {bytes} - the part contents

Returns {string} - the part's ETag

#Structs

#s3.Client

A configured S3 client: the endpoint (scheme + host, no trailing slash), the signing region, and the access-key pair. Value-semantic; build with connect.