feat: add listBuckets method

Author: c4spar

mod.ts

@@ -1,6 +1,7 @@
 export * from "./src/client.ts";
 export * from "./src/bucket.ts";
 export type {
+  Bucket,
   CommonPrefix,
   CopyDirective,
   CopyObjectOptions,
@@ -12,9 +13,11 @@ export type {
   GetObjectResponse,
   HeadObjectResponse,
   ListAllObjectsOptions,
+  ListBucketsResponses,
   ListObjectsOptions,
   ListObjectsResponse,
   LockMode,
+  Owner,
   PutObjectOptions,
   PutObjectResponse,
   ReplicationStatus,

src/bucket.ts

@@ -1,9 +1,4 @@
-import {
-  AWSSignerV4,
-  decodeXMLEntities,
-  parseXML,
-  pooledMap,
-} from "../deps.ts";
+import { AWSSignerV4, parseXML, pooledMap } from "../deps.ts";
 import type { S3Config } from "./client.ts";
 import type {
   CommonPrefix,
@@ -27,6 +22,8 @@ import { S3Error } from "./error.ts";
 import type { Signer } from "../deps.ts";
 import { doRequest, encodeURIS3 } from "./utils.ts";
 import type { Params } from "./utils.ts";
+import type { Document } from "./xml.ts";
+import { extractContent, extractField, extractRoot } from "./xml.ts";
 
 export interface S3BucketConfig extends S3Config {
   bucket: string;
@@ -330,9 +327,7 @@ export class S3Bucket {
     }
 
     const parsed = {
-      isTruncated: extractContent(root, "IsTruncated") === "true"
-        ? true
-        : false,
+      isTruncated: extractContent(root, "IsTruncated") === "true",
       contents: root.children
         .filter((node) => node.name === "Contents")
         .map<S3Object>((s3obj) => {
@@ -625,40 +620,3 @@ export class S3Bucket {
     return deleted;
   }
 }
-
-interface Document {
-  declaration: {
-    attributes: Record<string, unknown>;
-  };
-  root: Xml | undefined;
-}
-
-interface Xml {
-  name: string;
-  attributes: unknown;
-  children: Xml[];
-  content?: string;
-}
-
-function extractRoot(doc: Document, name: string): Xml {
-  if (!doc.root || doc.root.name !== name) {
-    throw new S3Error(
-      `Malformed XML document. Missing ${name} field.`,
-      JSON.stringify(doc, undefined, 2),
-    );
-  }
-  return doc.root;
-}
-
-function extractField(node: Xml, name: string): Xml | undefined {
-  return node.children.find((node) => node.name === name);
-}
-
-function extractContent(node: Xml, name: string): string | undefined {
-  const field = extractField(node, name);
-  const content = field?.content;
-  if (content === undefined) {
-    return content;
-  }
-  return decodeXMLEntities(content);
-}

src/client.ts

@@ -1,9 +1,16 @@
-import { AWSSignerV4 } from "../deps.ts";
-import type { CreateBucketOptions } from "./types.ts";
+import { AWSSignerV4, parseXML } from "../deps.ts";
+import type { CreateBucketOptions, ListBucketsResponses } from "./types.ts";
 import { S3Error } from "./error.ts";
 import { S3Bucket } from "./bucket.ts";
 import { doRequest, encoder } from "./utils.ts";
 import type { Params } from "./utils.ts";
+import {
+  extractContent,
+  extractField,
+  extractFields,
+  extractRoot,
+} from "./xml.ts";
+import type { Document } from "./xml.ts";
 
 export interface S3Config {
   region: string;
@@ -88,4 +95,44 @@ export class S3 {
       bucket,
     });
   }
+
+  async listBuckets(): Promise<ListBucketsResponses> {
+    const resp = await doRequest({
+      host: this.#host,
+      signer: this.#signer,
+      method: "GET",
+    });
+
+    if (resp.status !== 200) {
+      throw new S3Error(
+        `Failed to list buckets": ${resp.status} ${resp.statusText}`,
+        await resp.text(),
+      );
+    }
+
+    const xml = await resp.text();
+    return this.#parseListBucketsResponseXml(xml);
+  }
+
+  #parseListBucketsResponseXml(x: string): ListBucketsResponses {
+    const doc: Document = parseXML(x);
+    const root = extractRoot(doc, "ListAllMyBucketsResult");
+    const buckets = extractField(root, "Buckets")!;
+    const owner = extractField(root, "Owner")!;
+
+    return {
+      buckets: extractFields(buckets, "Bucket")
+        .map((bucket) => {
+          const creationDate = extractContent(bucket, "CreationDate");
+          return {
+            name: extractContent(bucket, "Name"),
+            creationDate: creationDate ? new Date(creationDate) : undefined,
+          };
+        }),
+      owner: {
+        id: extractContent(owner, "ID"),
+        displayName: extractContent(owner, "DisplayName"),
+      },
+    };
+  }
 }

src/client_test.ts

@@ -42,3 +42,17 @@ Deno.test({
     );
   },
 });
+
+Deno.test({
+  name: "[client] should list all buckets",
+  async fn() {
+    const { buckets, owner } = await s3.listBuckets();
+    assert(buckets.length, "no buckets available");
+    assertEquals(buckets[0].name, "test");
+    assert(
+      buckets[0].creationDate instanceof Date,
+      "creationDate is not of type Date",
+    );
+    assertEquals(owner.displayName, "minio");
+  },
+});

src/types.ts

@@ -566,3 +566,18 @@ export interface CreateBucketOptions {
   /** Allows grantee to write the ACL for the applicable bucket. */
   grantWriteAcp?: string;
 }
+
+export interface Bucket {
+  creationDate?: Date;
+  name?: string;
+}
+
+export interface Owner {
+  displayName?: string;
+  id?: string;
+}
+
+export interface ListBucketsResponses {
+  buckets: Array<Bucket>;
+  owner: Owner;
+}

src/utils.ts

@@ -10,8 +10,8 @@ export const encoder = new TextEncoder();
 interface S3RequestOptions {
   host: string;
   signer: Signer;
-  path: string;
   method: string;
+  path?: string;
   params?: Params;
   headers?: Params;
   body?: Uint8Array | undefined;
@@ -20,7 +20,7 @@ interface S3RequestOptions {
 export async function doRequest({
   host,
   signer,
-  path,
+  path = "/",
   params,
   method,
   headers,

src/xml.ts

@@ -0,0 +1,43 @@
+import { S3Error } from "./error.ts";
+import { decodeXMLEntities } from "../deps.ts";
+
+export interface Document {
+  declaration: {
+    attributes: Record<string, unknown>;
+  };
+  root: Xml | undefined;
+}
+
+export interface Xml {
+  name: string;
+  attributes: unknown;
+  children: Xml[];
+  content?: string;
+}
+
+export function extractRoot(doc: Document, name: string): Xml {
+  if (!doc.root || doc.root.name !== name) {
+    throw new S3Error(
+      `Malformed XML document. Missing ${name} field.`,
+      JSON.stringify(doc, undefined, 2),
+    );
+  }
+  return doc.root;
+}
+
+export function extractField(node: Xml, name: string): Xml | undefined {
+  return node.children.find((node) => node.name === name);
+}
+
+export function extractFields(node: Xml, name: string): Array<Xml> {
+  return node.children.filter((node) => node.name === name);
+}
+
+export function extractContent(node: Xml, name: string): string | undefined {
+  const field = extractField(node, name);
+  const content = field?.content;
+  if (content === undefined) {
+    return content;
+  }
+  return decodeXMLEntities(content);
+}