@stowage/adapter-s3 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Kaufmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# @stowage/adapter-s3
+
+A storage in one bucket of AWS S3 or Cloudflare R2, spoken to over the S3 wire protocol rather than
+through an SDK.
+
+## Install
+
+```sh
+npm install @stowage/adapter-s3
+```
+
+## Example
+
+A server signs a URL for one upload of the type and length the browser reported. The browser then
+calls it with a plain `fetch` and `PUT`, against AWS S3 or R2 alike.
+
+```ts
+import { fromEnv, s3Storage } from "@stowage/adapter-s3";
+
+declare const process: { readonly env: Readonly<Record<string, string | undefined>> };
+
+const aws = s3Storage({ bucket: "my-app-uploads", region: "eu-north-1", credentials: fromEnv });
+
+const fromR2Env = () => ({
+  accessKeyId: process.env.R2_ACCESS_KEY_ID ?? "",
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY ?? "",
+});
+
+const r2 = s3Storage({
+  bucket: "my-app-uploads",
+  region: "auto",
+  endpoint: "https://<account-id>.r2.cloudflarestorage.com",
+  credentials: fromR2Env,
+});
+
+for (const storage of [aws, r2]) {
+  const url = await storage.presignPut("avatars/alice.png", {
+    expiresIn: 300,
+    contentType: "image/png",
+    contentLength: 48_213,
+  });
+
+  console.log(url);
+}
+```
+
+The bucket has to allow `UNSIGNED-PAYLOAD` and carry a CORS rule for the uploading origin; stowage
+configures neither
+([flow 2](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/docs/spec.md#flow-2-browser-upload-through-a-presigned-put)).
+
+## Runtimes
+
+Node 24 and later, Bun, Deno and `workerd` at the compatibility date `2026-09-01`. `fromEnv` reads
+the environment on `workerd` under `nodejs_compat` and on Deno under `--allow-env`. CI last ran green on Bun 1.4.2 and Deno 2.9.6.
+
+The bundle measures 13.4 kB minified and gzipped, `@stowage/core` included.
+
+## Limits
+
+- `keyBytesPreserved` is not declared
+  ([spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/docs/spec.md#49-capabilities)).
+  R2 normalizes a key to NFC, so two Unicode-equivalent keys name one object there and two on AWS
+  S3.
+- Where AWS S3 and R2 answer differently, the adapter is written to the stricter side
+  ([spec 7.2](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/docs/spec.md#72-promised-providers)):
+
+| Point                              | What holds                                                                                                               |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Listing order                      | None. A page holds at most 1000 keys                                                                                     |
+| `userMetadata`                     | 2 KB of encoded header bytes; ASCII keys                                                                                 |
+| Single `PUT`                       | Up to 5 GB for a `Uint8Array` or string; a stream that fills more than one part goes as a multipart upload               |
+| Object size ceiling                | The provider's, answered with `EntityTooLarge`                                                                           |
+| `Content-Type`                     | Always sent by `put`, `application/octet-stream` where none was given                                                    |
+| `CompleteMultipartUpload`          | Judged by its body, which may carry an error under `200`                                                                 |
+| Writes per key                     | R2 answers `429` above one write per second and key; the retry may recover a single collision, but does not guarantee it |
+| Incomplete multipart uploads       | Removed by a lifecycle rule on AWS, after seven days by default on R2; stowage removes none                              |
+| Presigned URL host                 | The endpoint that signed it; on R2 the `r2.cloudflarestorage.com` endpoint and not a custom domain                       |
+| Response overrides on `presignGet` | Answered as the four response headers, on AWS and on R2                                                                  |
+
+## Notes
+
+No package takes a connection URL
+([spec 7.3](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/docs/spec.md#73-credentials)).
+A caller holding one splits it into the four options. `credentials: fromEnv` keeps the secret out of
+the URL; one that stays in it has to be percent-encoded, because a `/` in the secret makes
+`new URL` throw.
+
+```ts
+import { s3Storage, type S3Storage } from "@stowage/adapter-s3";
+
+// s3://<access-key-id>:<secret-access-key>@<bucket>?region=<region>&endpoint=<endpoint>
+export function s3StorageFromUrl(connection: string): S3Storage {
+  const url = new URL(connection);
+  const region = url.searchParams.get("region");
+
+  // The message quotes nothing of the URL, which carries the secret.
+  if (region === null) throw new Error("The connection URL names no region");
+
+  return s3Storage({
+    bucket: url.hostname,
+    region,
+    endpoint: url.searchParams.get("endpoint") ?? undefined,
+    credentials: {
+      accessKeyId: decodeURIComponent(url.username),
+      secretAccessKey: decodeURIComponent(url.password),
+    },
+  });
+}
+```
+
+`put` takes no `Blob`. A caller holding one passes its stream
+([spec 4.2](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/docs/spec.md#42-bodies)):
+
+```ts
+import { fromEnv, s3Storage } from "@stowage/adapter-s3";
+
+const storage = s3Storage({ bucket: "my-app-uploads", region: "eu-north-1", credentials: fromEnv });
+const blob = new Blob(["region,revenue\n"], { type: "text/csv" });
+
+await storage.put("reports/2026/q3.csv", blob.stream(), { contentType: blob.type });
+```
+
+stowage reports no progress, no upload id and no resume
+([spec 7.6](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/docs/spec.md#76-uploads)).
+A caller who wants progress counts the bytes on their way into `put`:
+
+```ts
+import { fromEnv, s3Storage } from "@stowage/adapter-s3";
+
+const storage = s3Storage({ bucket: "my-app-uploads", region: "eu-north-1", credentials: fromEnv });
+
+function countBytes(report: (bytes: number) => void): TransformStream<Uint8Array, Uint8Array> {
+  let bytes = 0;
+
+  return new TransformStream({
+    transform(chunk, controller) {
+      bytes += chunk.byteLength;
+      report(bytes);
+      controller.enqueue(chunk);
+    },
+  });
+}
+
+const response = await fetch("https://example.com/video.mp4");
+
+if (response.body === null) throw new Error("The response carries no body");
+
+await storage.put("videos/intro.mp4", response.body.pipeThrough(countBytes(console.log)), {
+  contentType: "video/mp4",
+});
+```
+
+## Specification
+
+[`docs/spec.md` at `@stowage/adapter-s3@0.1.0`](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/docs/spec.md#7-stowageadapter-s3)
+is the contract: a caller may rely on what it states and on nothing else this package happens to
+export. The [terms it uses](https://github.com/stowage-js/stowage/blob/@stowage/adapter-s3@0.1.0/CONTEXT.md)
+and the [decisions behind it](https://github.com/stowage-js/stowage/tree/@stowage/adapter-s3@0.1.0/docs/adr)
+are at the same tag.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { Resolvable, ResolverOptions, Storage } from "@stowage/core";
+//#region src/credentials.d.ts
+/**
+ * Checked before signing: `accessKeyId` and `secretAccessKey` are non-empty strings, and no
+ * key beyond these three is present. A violation is `InvalidCredentials` naming the field.
+ */
+interface S3Credentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+}
+/**
+ * A resolver, passed as `credentials: fromEnv` rather than called, so that a rotated
+ * `AWS_SESSION_TOKEN` reaches the next request. Reading the three variables again is
+ * what a refresh is here, so the options it is handed decide nothing (ADR 0007).
+ */
+export declare function fromEnv(_options?: ResolverOptions): S3Credentials;
+//#endregion
+//#region src/configuration.d.ts
+interface S3AdapterOptions {
+  bucket: string;
+  /** Sent as configured; nothing discovers it. R2 takes `"auto"`. */
+  region: string;
+  /**
+   * AWS S3 at `https://<bucket>.s3.<region>.amazonaws.com` where absent. Given, an absolute
+   * URL with no userinfo, no query and no fragment, `https:` always and `http:` only where the
+   * host is a loopback address; anything else is `InvalidOption` at construction.
+   */
+  endpoint?: string;
+  /** Addresses the bucket in the path rather than in the host name, which is the default. */
+  forcePathStyle?: boolean;
+  credentials: Resolvable<S3Credentials>;
+  /**
+   * How often one HTTP request is attempted while its failure is transient: a response of
+   * `408`, `429` or `5xx`, or none at all. `false` sends one attempt. Neither switches off
+   * the one repeat with a fresh credential after the provider answered `Expired`.
+   */
+  retry?: false | {
+    /** 1 to 3, and 3 where absent. Outside that range it is `InvalidOption`. */
+    maxAttempts?: number;
+  };
+  /** How a stream that fills more than one part is uploaded. */
+  multipart?: {
+    /**
+     * Bytes per part, 5 MiB to 5 GiB, and 8 MiB where absent. Outside that range it is
+     * `InvalidOption`. A stream needing more than 10,000 parts is `InvalidRequest`.
+     */
+    partSize?: number;
+    /** Parts in flight, 1 to 16, and 4 where absent. Outside that range it is `InvalidOption`. */
+    concurrency?: number;
+  };
+}
+//#endregion
+//#region src/presign.d.ts
+interface S3PresignGetOptions {
+  /** Seconds, 1 to 604800. The credential that signs may cut the lifetime shorter. */
+  expiresIn: number;
+  responseContentType?: string;
+  responseContentDisposition?: string;
+  responseCacheControl?: string;
+  responseExpires?: string;
+}
+interface S3PresignPutOptions {
+  /** Seconds, 1 to 604800. The credential that signs may cut the lifetime shorter. */
+  expiresIn: number;
+  /** Bound exactly: an upload of another type is refused by the provider. */
+  contentType: string;
+  /**
+   * Bound exactly, so the client reports the length and the server signs that number: an
+   * upload of another length is refused, and there is no upper bound to sign instead. A
+   * finite, non-negative integer; anything else is `InvalidOption` before signing.
+   */
+  contentLength: number;
+}
+//#endregion
+//#region src/index.d.ts
+export interface S3Storage extends Storage {
+  readonly provider: "s3";
+  /**
+   * A URL a client holding no credential calls with a plain `GET` for this one key until
+   * it expires. Whoever holds it may read the object: it is a bearer token. Sends no
+   * request, and works against the endpoint that signed it only.
+   */
+  presignGet(key: string, options: S3PresignGetOptions): Promise<string>;
+  /**
+   * A URL a client holding no credential calls with a plain `PUT` of one body under this
+   * key until it expires. `contentType` and `contentLength` bind exactly: the provider
+   * refuses a body of another type or another length, so a body of unknown length cannot
+   * be uploaded through it. It signs `UNSIGNED-PAYLOAD` and no checksum, so the upload
+   * carries no integrity check. Sends no request.
+   */
+  presignPut(key: string, options: S3PresignPutOptions): Promise<string>;
+}
+export declare function s3Storage(options: S3AdapterOptions): S3Storage;
+//#endregion
+export type { S3AdapterOptions, S3Credentials, S3PresignGetOptions, S3PresignPutOptions };