Add support for Requester Pays in S3 operations (#25514)

- Introduced `requestPayer` option in S3-related functions and
structures to handle Requester Pays buckets.
- Updated S3 client methods to accept and propagate the `requestPayer`
flag.
- Enhanced documentation for the `requestPayer` option in the S3 type
definitions.
- Adjusted existing S3 operations to utilize the `requestPayer`
parameter where applicable, ensuring compatibility with AWS S3's
Requester Pays feature.
- Ensured that the new functionality is integrated into multipart
uploads and simple requests.

### What does this PR do?

This change allows users to specify whether they are willing to pay for
data transfer costs when accessing objects in Requester Pays buckets,
improving flexibility and compliance with AWS S3's billing model.

This closes #25499

### How did you verify your code works?

I have added a new test file to verify this functionality, and all my
tests pass.
I also tested this against an actual S3 bucket which can only be
accessed if requester pays. I can confirm that it's accessible with
`requestPayer` is `true`, and the default of `false` does not allow
access.

An example bucket is here: s3://hl-mainnet-evm-blocks/0/0/1.rmp.lz4
(my usecase is indexing [hyperliquid block
data](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/hyperevm/raw-hyperevm-block-data)
which is stored in s3, and I want to use bun to index faster)

---------

Co-authored-by: Alistair Smith <hi@alistair.sh>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Ciro Spaciari <ciro.spaciari@gmail.com>

packages/bun-types/s3.d.ts

@@ -321,6 +321,30 @@ declare module "bun" {
       | "SNOW"
       | "STANDARD_IA";
 
+    /**
+     * When set to `true`, confirms that the requester knows they will be charged
+     * for the request and data transfer costs. Required for accessing objects
+     * in Requester Pays buckets.
+     *
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html
+     *
+     * @example
+     *    // Accessing a file in a Requester Pays bucket
+     *     const file = s3.file("data.csv", {
+     *       bucket: "requester-pays-bucket",
+     *       requestPayer: true
+     *     });
+     *     const content = await file.text();
+     *
+     * @example
+     *    // Uploading to a Requester Pays bucket
+     *     await s3.write("output.json", data, {
+     *       bucket: "requester-pays-bucket",
+     *       requestPayer: true
+     *     });
+     */
+    requestPayer?: boolean;
+
     /**
      * @deprecated The size of the internal buffer in bytes. Defaults to 5 MiB. use `partSize` and `queueSize` instead.
      */