Net::A...eatures(3pm)

📦
version 0.992 · 7 versions
, in ubuntu resolute, ubuntu stonking

💖 Net::Amazon::S3::Features — the manual, but make it make sense 💖

okay bestie, so this is the manual page for Net::Amazon::S3::Features (it's a 3pm page, so it's Perl module docs, iykyk). Let's get into it. ✨

🌸 NAME 🌸

Net::Amazon::S3::Features — literally just: Features available in Net::Amazon::S3 💅

Like. That's the whole vibe. It's the feature map. The lore. The "what does this thing actually support" doc.

⭐ VERSION ⭐

version 0.992 — yes, we're on that version, no cap 📌

👑 AUTHOR 👑

Branislav Zahradník <barney@cpan.org> — the main character who wrote this 🫶

This software is copyright (c) 2025 by:

  • Amazon Digital Services
  • Leon Brocard
  • Brad Fitzpatrick
  • Pedro Figueiredo
  • Rusty Conover
  • Branislav Zahradník

And the license situation, fr fr:

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

so like. it's free. you can share it, you can remix it, same terms as Perl 5 itself. slay. 💖

🦋 API COMPARISON 🦋

Okay so here's the tea: Net::Amazon::S3 supports two APIs, and they do not have the same feature support. Not even close. So this is your cheat sheet for which one does what. 🗺️

And a note that's giving very "this is current as of now":

This document describes current behaviour.

like, this is the current state of things. not the past, not the future. present tense only. 💅

✨ Error reporting ✨

So when errors happen — and bestie, they will happen — this is the default error reporting method situation. Three flavors, pick your fighter:

🍓 set S3 err

Operation returns expression evaluated as false and err with errstr are populated from response content.

(so: falsy return, and err + errstr get filled in from whatever the response content said.)

See Net::Amazon::S3::Error::Handler::Status, Net::Amazon::S3::Error::Handler::Legacy.

🌈 set network error

Populates S3 err with the network_error constant, and S3 errstr with the http status line (eg: 404 Not Found) — and then it throws.

See Net::Amazon::S3::Error::Handler::Legacy.

💀 confess

Operation throws using confess.

(yeah, it just. confesses. no chill.)

See Net::Amazon::S3::Error::Handler::Confess.

🔥 Feature support 🔥

For the full details, go look at the corresponding api-operation / client-operation test file. 👀 That's where the real receipts live.

And also here's the list of Amazon S3 Operations if you wanna see the whole menu of what AWS itself offers:

https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html

okay that's part one bestie, don't go anywhere — 📌 more is coming. 🫶

okay so we're still in the middle of this giant comparison table and it just keeps going, bestie. 😭 quick legend so you're not lost: blue = Net::Amazon::S3 (the API one) and purple = Net::Amazon::S3::Client. every op shows the call, then any sub-flags, then what it returns and what it does on errors. a big fat ❌ means that side literally does not have it. not me being devastated on its behalf 💀

  • AbortMultipartUpload
    • Net::Amazon::S3 (API): ❌ · returns: ❌ · errors: ❌
    • Net::Amazon::S3::Client: object->abort_multipart_upload · returns: http response · errors: confess
  • CompleteMultipartUpload
    • Net::Amazon::S3 (API): ❌ · returns: ❌ · errors: ❌
    • Net::Amazon::S3::Client: object->complete_multipart_upload · returns: http response · errors: confess
  • CreateBucket 🪣 the main character of every S3 story
    • Net::Amazon::S3 (API): s3->add_bucket · with region: ✅ · returns: Bucket instance · errors: set S3 err
    • Net::Amazon::S3::Client: client->create_bucket · with region: ✅ · returns: Bucket instance · errors: confess
  • CreateMultipartUpload
    • Net::Amazon::S3 (API): ❌ · returns: ❌ · errors: ❌
    • Net::Amazon::S3::Client: object->initiate_multipart_upload · returns: http response · errors: confess
  • DeleteBucket
    • Net::Amazon::S3 (API): s3->delete_bucket · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->delete · returns: boolean · errors: confess
  • DeleteBucketTagging
    • Net::Amazon::S3 (API): bucket->delete_tags · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->delete_tags · returns: boolean · errors: confess
  • DeleteObject
    • Net::Amazon::S3 (API): bucket->delete_key · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->object->delete · returns: boolean · errors: confess
  • DeleteObjects — the multi-delete one, chunks itself, obsessed with efficiency ✨
    • Net::Amazon::S3 (API): bucket->delete_multi_object · auto chunks: ✅ · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->delete_multi_object · auto chunks: ✅ · returns: HTTP::Response object · errors: confess
  • DeleteObjectTagging
    • Net::Amazon::S3 (API): bucket->delete_tags · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->object->delete_tags · returns: boolean · errors: confess
  • GetBucketAcl
    • Net::Amazon::S3 (API): bucket->get_acl · returns: response body (XML) (undef on Not Found) · errors: set network error (none on Not Found)
    • Net::Amazon::S3::Client: bucket->acl · returns: response body (XML) · errors: confess
  • GetBucketLocation 🌍
    • Net::Amazon::S3 (API): bucket->get_location_constraint · returns: location (Str) · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->get_location_constraint · returns: location (Str) · errors: confess
  • GetObject — the one you'll call a million times fr fr
    • Net::Amazon::S3 (API): bucket->get_key · into file: ✅, bucket->get_key_filename · into callback: ❌ · returns: struct with value (undef on Not Found) · errors: set network error (none on Not Found)
    • Net::Amazon::S3::Client: bucket->object->get · into file: ✅, bucket->object->get_filename · into callback: ✅, bucket->object->get_callback · returns: value · errors: confess
  • GetObjectAcl
    • Net::Amazon::S3 (API): bucket->get_acl · returns: response body (XML) (undef on Not Found) · errors: set network error (none on Not Found)
    • Net::Amazon::S3::Client: ❌ · returns: ❌ · errors: ❌
  • ListBuckets
    • Net::Amazon::S3 (API): s3->buckets · returns: Bucket instances in struct · errors: set S3 err
    • Net::Amazon::S3::Client: client->buckets · returns: Bucket instances (list) · errors: confess
  • ListObjects
    • Net::Amazon::S3 (API): s3->list_bucket · common prefixes: ✅ · list all: ✅, s3->list_bucket_all · returns: struct with list · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->list · common prefixes: ❌ · list all: ✅ · returns: iterator (Object list) · errors: confess during iteration
lowkey the "confess during iteration" thing matters, bestie — the error can show up while you're looping, not just when you call it. 👀
  • ListObjectsV2
    • API: ❌ · Client: ❌
  • ListParts
    • API: ❌ · Client: ❌
  • PutBucketAcl
    • Net::Amazon::S3 (API): bucket->set_acl · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->set_acl · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: confess
  • PutBucketTagging
    • Net::Amazon::S3 (API): bucket->add_tags · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->add_tags · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: confess
  • PutObject
    • Net::Amazon::S3 (API): bucket->add_key · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->object->put · returns: empty string · errors: confess
  • PutObjectAcl
    • Net::Amazon::S3 (API): bucket->set_acl · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: object->set_acl · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: confess
  • PutObjectTagging
    • Net::Amazon::S3 (API): bucket->add_tags · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: set S3 err
    • Net::Amazon::S3::Client: bucket->object->add_tags · with canned acl: ✅, as acl · with explicit acl: ✅, as acl · with xml acl: ✅, as acl_xml · returns: boolean · errors: confess
  • RestoreObject 🧚
    • Net::Amazon::S3 (API): ❌
    • Net::Amazon::S3::Client: bucket->object->restore

and yeah the table just keeps going, so hold that thought 🫶 there's still more below, don't go anywhere 💖

okay so the comparison table literally would not stop talking, and these next rows are the rest of it — same three-column situation, read it left to right, no cap 💅

  • returns | ❌ | http response
  • errors | ❌ | confess

next up, the UploadPart situation 🫶

  • UploadPart | ❌ | bucket->object->put_part
  • - from value | ❌ | ✅
  • - from file | ❌ | ❌
  • - from file chunk | ❌ | ❌
  • returns | ❌ | http response
  • errors | ❌ | confess

object-copy, where the left side finally wakes up and the right side takes a nap 😭

  • object-copy | bucket->copy_key | ❌
  • returns | boolean | ❌
  • errors | set S3 err | ❌

and last one, object-head — yes bestie, that middle cell is genuinely empty, it's not me being mysterious 🙈

  • object-head | | ❌
  • returns | boolean | ❌
  • errors | set S3 err | ❌

🌈 TODO plan (asorted, without time-plan) 🌈

this part is the wishlist, the vision board, the "we'll get to it" energy ✨

so that's the whole page, babes 💖 it went out under perl v5.40.1, dated 2025-12-07, on the Net::A...eatures(3pm) page — that's the footer saying its goodbyes, and I'm saying mine too 🦋 periodt 🌸

📦 where this page comes from