s3mini 0.1.0

package/src/consts.ts

@@ -0,0 +1,38 @@
+// Constants
+export const AWS_ALGORITHM = 'AWS4-HMAC-SHA256';
+export const AWS_REQUEST_TYPE = 'aws4_request';
+export const S3_SERVICE = 's3';
+export const LIST_TYPE = '2';
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
+export const DEFAULT_STREAM_CONTENT_TYPE = 'application/octet-stream';
+export const XML_CONTENT_TYPE = 'application/xml';
+export const JSON_CONTENT_TYPE = 'application/json';
+// List of keys that might contain sensitive information
+export const SENSITIVE_KEYS_REDACTED = ['accessKeyId', 'secretAccessKey', 'sessionToken', 'password', 'token'];
+export const DEFAULT_REQUEST_SIZE_IN_BYTES = 8 * 1024 * 1024;
+
+// Headers
+export const HEADER_AMZ_CONTENT_SHA256 = 'x-amz-content-sha256';
+export const HEADER_AMZ_DATE = 'x-amz-date';
+export const HEADER_HOST = 'host';
+export const HEADER_AUTHORIZATION = 'Authorization';
+export const HEADER_CONTENT_TYPE = 'Content-Type';
+export const HEADER_CONTENT_LENGTH = 'Content-Length';
+export const HEADER_ETAG = 'etag';
+export const HEADER_LAST_MODIFIED = 'last-modified';
+
+// Error messages
+export const ERROR_PREFIX = '[s3mini] ';
+export const ERROR_ACCESS_KEY_REQUIRED = `${ERROR_PREFIX}accessKeyId must be a non-empty string`;
+export const ERROR_SECRET_KEY_REQUIRED = `${ERROR_PREFIX}secretAccessKey must be a non-empty string`;
+export const ERROR_ENDPOINT_REQUIRED = `${ERROR_PREFIX}endpoint must be a non-empty string`;
+export const ERROR_ENDPOINT_FORMAT = `${ERROR_PREFIX}endpoint must be a valid URL. Expected format: https://<host>[:port][/base-path]`;
+export const ERROR_KEY_REQUIRED = `${ERROR_PREFIX}key must be a non-empty string`;
+export const ERROR_UPLOAD_ID_REQUIRED = `${ERROR_PREFIX}uploadId must be a non-empty string`;
+export const ERROR_PARTS_REQUIRED = `${ERROR_PREFIX}parts must be a non-empty array`;
+export const ERROR_INVALID_PART = `${ERROR_PREFIX}Each part must have a partNumber (number) and ETag (string)`;
+export const ERROR_DATA_BUFFER_REQUIRED = `${ERROR_PREFIX}data must be a Buffer or string`;
+// const ERROR_PATH_REQUIRED = `${ERROR_PREFIX}path must be a string`;
+export const ERROR_PREFIX_TYPE = `${ERROR_PREFIX}prefix must be a string`;
+export const ERROR_MAX_KEYS_TYPE = `${ERROR_PREFIX}maxKeys must be a positive integer`;
+export const ERROR_DELIMITER_REQUIRED = `${ERROR_PREFIX}delimiter must be a string`;

package/src/index.ts

@@ -0,0 +1,20 @@
+'use strict';
+
+import { s3mini } from './S3.js';
+import { sanitizeETag, runInBatches } from './utils.js';
+
+// Export the S3 class as default export and named export
+export { s3mini, sanitizeETag, runInBatches };
+export default s3mini;
+
+// Re-export types
+export type {
+  S3Config,
+  Logger,
+  UploadPart,
+  CompleteMultipartUploadResult,
+  ExistResponseCode,
+  ListBucketResponse,
+  ListMultipartUploadResponse,
+  ErrorWithCode,
+} from './types.js';

package/src/types.ts

@@ -0,0 +1,88 @@
+import type { createHash as NodeCreateHash, createHmac as NodeCreateHmac } from 'node:crypto';
+
+export interface S3Config {
+  accessKeyId: string;
+  secretAccessKey: string;
+  endpoint: string;
+  region?: string;
+  requestSizeInBytes?: number;
+  requestAbortTimeout?: number;
+  logger?: Logger;
+}
+
+export interface Crypto {
+  createHmac: typeof NodeCreateHmac;
+  createHash: typeof NodeCreateHash;
+}
+
+export interface Logger {
+  info: (message: string, ...args: unknown[]) => void;
+  warn: (message: string, ...args: unknown[]) => void;
+  error: (message: string, ...args: unknown[]) => void;
+}
+
+export interface UploadPart {
+  partNumber: number;
+  etag: string;
+}
+
+export interface CompleteMultipartUploadResult {
+  location: string;
+  bucket: string;
+  key: string;
+  etag: string;
+  eTag: string; // for backward compatibility
+  ETag: string; // for backward compatibility
+}
+
+interface ListBucketResult {
+  keyCount: string;
+  contents?: Array<Record<string, unknown>>;
+}
+interface ListBucketError {
+  error: { code: string; message: string };
+}
+
+export type ListBucketResponse = { listBucketResult: ListBucketResult } | { error: ListBucketError };
+
+export interface ListMultipartUploadSuccess {
+  listMultipartUploadsResult: {
+    bucket: string;
+    key: string;
+    uploadId: string;
+    size?: number;
+    mtime?: Date | undefined;
+    etag?: string;
+    eTag?: string; // for backward compatibility
+    parts: UploadPart[];
+    isTruncated: boolean;
+    uploads: UploadPart[];
+  };
+}
+
+export interface MultipartUploadError {
+  error: {
+    code: string;
+    message: string;
+  };
+}
+
+export interface ErrorWithCode {
+  code?: string;
+  cause?: { code?: string };
+}
+
+export type ListMultipartUploadResponse = ListMultipartUploadSuccess | MultipartUploadError;
+
+export type HttpMethod = 'POST' | 'GET' | 'HEAD' | 'PUT' | 'DELETE';
+
+// false - Not found (404)
+// true - Found (200)
+// null - ETag mismatch (412)
+export type ExistResponseCode = false | true | null;
+
+export type XmlValue = string | XmlMap | boolean | number | null;
+export interface XmlMap {
+  [key: string]: XmlValue | XmlValue[]; // one or many children
+  [key: number]: XmlValue | XmlValue[]; // allow numeric keys
+}

package/src/utils.ts

@@ -0,0 +1,197 @@
+'use strict';
+
+import type { Crypto, XmlValue, XmlMap, ListBucketResponse, ErrorWithCode } from './types.js';
+declare const crypto: Crypto;
+
+// Initialize crypto functions
+const _createHmac: Crypto['createHmac'] = crypto.createHmac || (await import('node:crypto')).createHmac;
+const _createHash: Crypto['createHash'] = crypto.createHash || (await import('node:crypto')).createHash;
+
+/**
+ * Hash content using SHA-256
+ * @param {string|Buffer} content  – data to hash
+ * @returns {string} Hex encoded hash
+ */
+export const hash = (content: string | Buffer): string => {
+  return _createHash('sha256').update(content).digest('hex');
+};
+
+/**
+ * Compute HMAC-SHA-256 of arbitrary data and return a hex string.
+ * @param {string|Buffer} key      – secret key
+ * @param {string|Buffer} content  – data to authenticate
+ * @param {BufferEncoding} [encoding='hex'] – hex | base64 | …
+ * @returns {string | Buffer} hex encoded HMAC
+ */
+export const hmac = (key: string | Buffer, content: string | Buffer, encoding?: 'hex' | 'base64'): string | Buffer => {
+  const mac = _createHmac('sha256', key).update(content);
+  return encoding ? mac.digest(encoding) : mac.digest();
+};
+
+/**
+ * Sanitize ETag value by removing quotes and XML entities
+ * @param etag ETag value to sanitize
+ * @returns Sanitized ETag
+ */
+export const sanitizeETag = (etag: string): string => {
+  const replaceChars: Record<string, string> = {
+    '"': '',
+    '&quot;': '',
+    '&#34;': '',
+    '&QUOT;': '',
+    '&#x00022': '',
+  };
+  return etag.replace(/^("|&quot;|&#34;)|("|&quot;|&#34;)$/g, m => replaceChars[m] as string);
+};
+
+const entityMap = {
+  '&quot;': '"',
+  '&apos;': "'",
+  '&lt;': '<',
+  '&gt;': '>',
+  '&amp;': '&',
+} as const;
+
+const unescapeXml = (value: string): string =>
+  value.replace(/&(quot|apos|lt|gt|amp);/g, m => entityMap[m as keyof typeof entityMap] ?? m);
+
+/**
+ * Parse a very small subset of XML into a JS structure.
+ *
+ * @param input raw XML string
+ * @returns string for leaf nodes, otherwise a map of children
+ */
+export const parseXml = (input: string): XmlValue => {
+  const RE_TAG = /<(\w)([-\w]+)(?:\/|[^>]*>((?:(?!<\1)[\s\S])*)<\/\1\2)>/gm;
+  const result: XmlMap = {}; // strong type, no `any`
+  let match: RegExpExecArray | null;
+
+  while ((match = RE_TAG.exec(input)) !== null) {
+    const [, prefix = '', key, inner] = match;
+    const fullKey = `${prefix.toLowerCase()}${key}`;
+    const node: XmlValue = inner ? parseXml(inner) : '';
+
+    const current = result[fullKey];
+    if (current === undefined) {
+      // first occurrence
+      result[fullKey] = node;
+    } else if (Array.isArray(current)) {
+      // already an array
+      current.push(node);
+    } else {
+      // promote to array on the second occurrence
+      result[fullKey] = [current, node];
+    }
+  }
+
+  // No child tags? — return the text, after entity decode
+  return Object.keys(result).length > 0 ? result : unescapeXml(input);
+};
+
+/**
+ * Encode a character as a URI percent-encoded hex value
+ * @param c Character to encode
+ * @returns Percent-encoded character
+ */
+const encodeAsHex = (c: string): string => `%${c.charCodeAt(0).toString(16).toUpperCase()}`;
+
+/**
+ * Escape a URI string using percent encoding
+ * @param uriStr URI string to escape
+ * @returns Escaped URI string
+ */
+export const uriEscape = (uriStr: string): string => {
+  return encodeURIComponent(uriStr).replace(/[!'()*]/g, encodeAsHex);
+};
+
+/**
+ * Escape a URI resource path while preserving forward slashes
+ * @param string URI path to escape
+ * @returns Escaped URI path
+ */
+export const uriResourceEscape = (string: string): string => {
+  return uriEscape(string).replace(/%2F/g, '/');
+};
+
+export const isListBucketResponse = (value: unknown): value is ListBucketResponse => {
+  return typeof value === 'object' && value !== null && ('listBucketResult' in value || 'error' in value);
+};
+
+export const extractErrCode = (e: unknown): string | undefined => {
+  if (typeof e !== 'object' || e === null) {
+    return undefined;
+  }
+  const err = e as ErrorWithCode;
+  if (typeof err.code === 'string') {
+    return err.code;
+  }
+  return typeof err.cause?.code === 'string' ? err.cause.code : undefined;
+};
+
+export class S3Error extends Error {
+  readonly code?: string;
+  constructor(msg: string, code?: string, cause?: unknown) {
+    super(msg);
+    this.name = new.target.name; // keeps instanceof usable
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+export class S3NetworkError extends S3Error {}
+export class S3ServiceError extends S3Error {
+  readonly status: number;
+  readonly serviceCode?: string;
+  body: string | undefined;
+  constructor(msg: string, status: number, serviceCode?: string, body?: string) {
+    super(msg, serviceCode);
+    this.status = status;
+    this.serviceCode = serviceCode;
+    this.body = body;
+  }
+}
+
+/**
+ * Run async-returning tasks in batches with an *optional* minimum
+ * spacing (minIntervalMs) between the *start* times of successive batches.
+ *
+ * @param {Iterable<() => Promise<unknonw>>} tasks       – functions returning Promises
+ * @param {number} [batchSize=30]                    – max concurrent requests
+ * @param {number} [minIntervalMs=0]                 – ≥0; 0 means “no pacing”
+ * @returns {Promise<Array<PromiseSettledResult<unknonw>>>}
+ */
+export const runInBatches = async (
+  tasks: Iterable<() => Promise<unknown>>,
+  batchSize = 30,
+  minIntervalMs = 0,
+): Promise<Array<PromiseSettledResult<unknown>>> => {
+  const allResults: PromiseSettledResult<unknown>[] = [];
+  let batch: Array<() => Promise<unknown>> = [];
+
+  for (const task of tasks) {
+    batch.push(task);
+    if (batch.length === batchSize) {
+      await executeBatch(batch);
+      batch = [];
+    }
+  }
+  if (batch.length) {
+    await executeBatch(batch);
+  }
+  return allResults;
+
+  // ───────── helpers ──────────
+  async function executeBatch(batchFns: Array<() => Promise<unknown>>): Promise<void> {
+    const start = Date.now();
+
+    const settled = await Promise.allSettled(batchFns.map(fn => fn()));
+    allResults.push(...settled);
+
+    if (minIntervalMs > 0) {
+      const wait = minIntervalMs - (Date.now() - start);
+      if (wait > 0) {
+        await new Promise(r => setTimeout(r, wait));
+      }
+    }
+  }
+};