@nextlyhq/storage-s3 0.0.2-alpha.62 → 0.0.2-alpha.65

package/dist/index.mjs

@@ -3,6 +3,483 @@ import { Upload } from '@aws-sdk/lib-storage';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 
 // src/adapter.ts
+
+// ../nextly/dist/chunk-HJ5IQPOY.mjs
+function isDbError(err) {
+  if (!err || typeof err !== "object") return false;
+  const obj = err;
+  return obj.name === "DbError" && typeof obj.kind === "string";
+}
+var NEXTLY_ERROR_STATUS = {
+  VALIDATION_ERROR: 400,
+  INVALID_INPUT: 400,
+  AUTH_REQUIRED: 401,
+  AUTH_INVALID_CREDENTIALS: 401,
+  TOKEN_EXPIRED: 401,
+  FORBIDDEN: 403,
+  // The schema builder is off in this environment (production by default).
+  // Separate from FORBIDDEN: the caller's permissions are not the problem.
+  BUILDER_DISABLED: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  DUPLICATE: 409,
+  RATE_LIMITED: 429,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  // 422: understood, well-formed, and refused on a rule the caller can act on.
+  // Deliberately NOT added to CANONICAL_CODE_FOR_STATUS -- that list drives the
+  // status -> code direction, where 422 stays mapped to INVALID_INPUT.
+  BUSINESS_RULE_VIOLATION: 422,
+  INTERNAL_ERROR: 500,
+  DATABASE_ERROR: 500,
+  EXTERNAL_SERVICE_ERROR: 502,
+  SERVICE_UNAVAILABLE: 503,
+  // Outbound-fetch safety (utils/validate-external-url): a URL refused for SSRF
+  // safety, and a fetch that timed out / exceeded the size cap / failed to decode.
+  EXTERNAL_URL_BLOCKED: 400,
+  EXTERNAL_REQUEST_FAILED: 502,
+  FILENAME_INVALID: 400,
+  EXTENSION_BLOCKED: 400,
+  MIME_BLOCKED: 415,
+  MIME_NOT_ALLOWED: 415,
+  SIZE_EXCEEDED: 413,
+  // A stored object exceeded the cap a READ was given, which is a different
+  // question from SIZE_EXCEEDED above: that one refuses an upload the caller
+  // is sending, this one refuses to buffer an object already stored. Kept
+  // apart so a caller discriminating on the code cannot match both.
+  STORAGE_READ_TOO_LARGE: 413,
+  // A stored object did not answer within the deadline the read was given. 504
+  // rather than 500 because the failure is the BACKEND not answering, and a
+  // caller can act on that difference: a gateway timeout is worth retrying, an
+  // internal error is not.
+  STORAGE_READ_TIMEOUT: 504,
+  // The store answered, and answered badly. 502 rather than 500 because the
+  // fault is UPSTREAM of this process: a caller can retry it, and an operator
+  // reading the log needs to look at the bucket rather than at this service.
+  // Distinct from the timeout above, which never got an answer at all.
+  STORAGE_READ_UNREACHABLE: 502,
+  MAGIC_BYTE_MISMATCH: 400,
+  SVG_SANITIZATION_FAILED: 400,
+  UNSUPPORTED_FOR_BACKEND: 415,
+  // Plan B — schema bookkeeping consolidation.
+  NEXTLY_LEGACY_BOOKKEEPING_DETECTED: 409,
+  NEXTLY_UPGRADE_TABLE_NAME_COLLISION: 409,
+  NEXTLY_UPGRADE_IN_PROGRESS: 409,
+  // Plan C2 — nextly migrate phases.
+  NEXTLY_MIGRATE_LOCK_BUSY: 409,
+  NEXTLY_BASELINE_LOCK_NOT_HELD: 409,
+  NEXTLY_RESOLVE_LOCK_NOT_HELD: 409,
+  // Boot refused to serve: the migrate lock stayed held past the wait deadline,
+  // so this process never established whether the schema matches the code. 503
+  // rather than 409 — a load balancer should take the instance out of rotation
+  // and retry it, which is exactly the recovery this refusal wants.
+  NEXTLY_BOOT_MIGRATIONS_NOT_RUN: 503,
+  // Still running rather than refused. 503 for the same reason: retry shortly.
+  NEXTLY_BOOT_MIGRATIONS_PENDING: 503,
+  NEXTLY_CORE_DESTRUCTIVE_REFUSED: 409,
+  NEXTLY_MIGRATION_DRIFT: 409,
+  NEXTLY_MIGRATION_APPLY_FAILED: 500,
+  // Plan C3 — migrate:resolve recovery command.
+  NEXTLY_MIGRATION_FILE_MISSING: 404,
+  NEXTLY_MIGRATION_SNAPSHOT_MISSING: 404,
+  NEXTLY_MIGRATION_RESOLVE_DRIFT: 409,
+  NEXTLY_MIGRATION_RESOLVE_PRECONDITION: 409,
+  // Plan D — UI schema support.
+  NEXTLY_UI_SCHEMA_INVALID: 400,
+  NEXTLY_SCHEMA_SLUG_COLLISION: 409,
+  NEXTLY_SCHEMA_RELATION_TARGET_MISSING: 400,
+  // Plugin platform (P2b) — schema extend (contributes.extend) + relations (D15).
+  NEXTLY_SCHEMA_EXTEND_TARGET_UNKNOWN: 400,
+  NEXTLY_SCHEMA_EXTEND_FIELD_DUPLICATE: 409,
+  NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION: 409,
+  // Plugin platform (P2c) — framework remap (.rename()).
+  NEXTLY_SCHEMA_RENAME_UNKNOWN_TARGET: 400,
+  // Plugin platform — a declared admin.clientConfig that cannot be delivered
+  // to the browser, refused at boot rather than serialized mangled.
+  NEXTLY_PLUGIN_CLIENT_CONFIG_INVALID: 500,
+  // Plugin platform — a contributed admin widget that cannot be delivered to
+  // the browser. Refused at boot because it is serialized into the ONE
+  // `/api/admin-meta/workspace` payload: a value `JSON.stringify` throws on
+  // fails that request for every admin, not just the widget's own card.
+  NEXTLY_PLUGIN_ADMIN_WIDGET_INVALID: 500,
+  // Plugin platform (P0) — boot-time plugin dependency/version resolution.
+  PLUGIN_RESOLUTION_ERROR: 500,
+  // Plugin platform (P4) — contributes.routes collection (D25).
+  NEXTLY_ROUTE_COLLISION: 409,
+  NEXTLY_ROUTE_INVALID_PATH: 400,
+  // An email transport whose library is an optional peer dependency the host
+  // has not installed. 503 rather than 500: the request is not malformed and
+  // nothing is broken, the install simply cannot carry it out yet, and the
+  // remedy is one command on the server rather than a change by the caller.
+  NEXTLY_EMAIL_TRANSPORT_UNAVAILABLE: 503,
+  // The tooling that compiles `nextly.config.ts` is an optional peer the host
+  // has not installed. 503 rather than 500 for the same reason as the mail
+  // transport above: nothing is broken and the request is not malformed, the
+  // install simply cannot carry it out until one command is run.
+  NEXTLY_CONFIG_TOOLING_UNAVAILABLE: 503
+};
+var CANONICAL_CODE_FOR_STATUS = [
+  "VALIDATION_ERROR",
+  "AUTH_REQUIRED",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "CONFLICT",
+  "PAYLOAD_TOO_LARGE",
+  "UNSUPPORTED_MEDIA_TYPE",
+  "RATE_LIMITED",
+  "EXTERNAL_SERVICE_ERROR",
+  "SERVICE_UNAVAILABLE"
+];
+({
+  ...Object.fromEntries(
+    CANONICAL_CODE_FOR_STATUS.map((code) => [NEXTLY_ERROR_STATUS[code], code])
+  )});
+var DB_ERROR_MAPPING = {
+  "unique-violation": {
+    code: "DUPLICATE",
+    statusCode: 409,
+    publicMessage: "Resource already exists."
+  },
+  "fk-violation": {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "Referenced record does not exist."
+  },
+  "not-null-violation": {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "A required field is missing."
+  },
+  constraint: {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "The provided data violates a constraint."
+  },
+  deadlock: {
+    code: "CONFLICT",
+    statusCode: 409,
+    publicMessage: "The operation could not be completed. Please retry."
+  },
+  "serialization-failure": {
+    code: "CONFLICT",
+    statusCode: 409,
+    publicMessage: "The operation could not be completed. Please retry."
+  },
+  timeout: {
+    code: "DATABASE_ERROR",
+    statusCode: 500,
+    publicMessage: "The operation timed out. Please try again."
+  },
+  "connection-lost": {
+    code: "DATABASE_ERROR",
+    statusCode: 500,
+    publicMessage: "A temporary database error occurred. Please try again."
+  },
+  syntax: {
+    code: "INTERNAL_ERROR",
+    statusCode: 500,
+    publicMessage: "An unexpected error occurred."
+  },
+  internal: {
+    code: "INTERNAL_ERROR",
+    statusCode: 500,
+    publicMessage: "An unexpected error occurred."
+  }
+};
+var NEXTLY_ERROR_BRAND = Symbol.for("nextly/NextlyError");
+function hasBrand(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    return false;
+  }
+  return value[NEXTLY_ERROR_BRAND] === true;
+}
+var NextlyError = class _NextlyError extends Error {
+  code;
+  statusCode;
+  publicMessage;
+  publicData;
+  messageKey;
+  logMessage;
+  logContext;
+  cause;
+  timestamp;
+  constructor(opts) {
+    super(opts.publicMessage);
+    this.name = "NextlyError";
+    this.code = opts.code;
+    this.publicMessage = opts.publicMessage;
+    this.publicData = opts.publicData;
+    this.messageKey = opts.messageKey;
+    this.logMessage = opts.logMessage;
+    this.logContext = opts.logContext;
+    this.cause = opts.cause;
+    this.timestamp = /* @__PURE__ */ new Date();
+    this.statusCode = _NextlyError.resolveStatusCode(opts);
+    Error.captureStackTrace?.(this, _NextlyError);
+  }
+  static {
+    _NextlyError.prototype[NEXTLY_ERROR_BRAND] = true;
+  }
+  static resolveStatusCode(opts) {
+    if (typeof opts.statusCode === "number") return opts.statusCode;
+    if (opts.code in NEXTLY_ERROR_STATUS) {
+      return NEXTLY_ERROR_STATUS[opts.code];
+    }
+    return 500;
+  }
+  /** HTTP-safe JSON. Strips logMessage / logContext / cause / stack. */
+  toResponseJSON(requestId) {
+    const json = {
+      code: String(this.code),
+      message: this.publicMessage,
+      requestId
+    };
+    if (this.messageKey) json.messageKey = this.messageKey;
+    if (this.publicData !== void 0) json.data = this.publicData;
+    return json;
+  }
+  /** Operator-facing JSON for log lines. Includes everything. */
+  toLogJSON(requestId) {
+    return {
+      code: this.code,
+      statusCode: this.statusCode,
+      publicMessage: this.publicMessage,
+      messageKey: this.messageKey,
+      logMessage: this.logMessage,
+      logContext: this.logContext,
+      cause: this.cause ? {
+        name: this.cause.name,
+        message: this.cause.message,
+        stack: this.cause.stack
+      } : void 0,
+      timestamp: this.timestamp.toISOString(),
+      requestId
+    };
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Static factories — the recommended throw site for every common case.
+  // Public messages here follow the §13.8 rubric: complete sentence,
+  // generic, no identifiers, no value echoing, no policy hints.
+  // ────────────────────────────────────────────────────────────────────
+  static invalidCredentials(opts) {
+    return new _NextlyError({
+      code: "AUTH_INVALID_CREDENTIALS",
+      publicMessage: "Invalid email or password.",
+      logMessage: "Login failed",
+      logContext: opts?.logContext
+    });
+  }
+  static authRequired(opts) {
+    return new _NextlyError({
+      code: "AUTH_REQUIRED",
+      publicMessage: "Authentication required.",
+      logContext: opts?.logContext
+    });
+  }
+  /**
+   * Distinct from `authRequired`: the caller was authenticated but the
+   * session token expired. Clients key on the TOKEN_EXPIRED *code* to
+   * silently refresh and retry rather than redirecting to login; the public
+   * message stays the generic spec §13.6 string ("Authentication required.")
+   * so the wire never reveals the session state — same as `authRequired`.
+   */
+  static tokenExpired(opts) {
+    return new _NextlyError({
+      code: "TOKEN_EXPIRED",
+      publicMessage: "Authentication required.",
+      logContext: opts?.logContext
+    });
+  }
+  static notFound(opts) {
+    return new _NextlyError({
+      code: "NOT_FOUND",
+      publicMessage: opts?.message ?? "Not found.",
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  static forbidden(opts) {
+    return new _NextlyError({
+      code: "FORBIDDEN",
+      publicMessage: "You don't have permission to perform this action.",
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  /**
+   * A call the caller got wrong, where naming the mistake IS the value of the
+   * error.
+   *
+   * The only factory that takes its public message from the caller. The
+   * generic messages elsewhere exist so an HTTP response cannot leak internal
+   * detail; this one is for arguments and configuration a developer controls
+   * and must be told about — a missing option, an unusable combination — where
+   * `internal()` would reduce the one useful sentence to "An unexpected error
+   * occurred." Do not pass user-supplied data through it.
+   */
+  static invalidInput(opts) {
+    return new _NextlyError({
+      code: "INVALID_INPUT",
+      publicMessage: opts.message,
+      logContext: opts.logContext
+    });
+  }
+  static validation(opts) {
+    return new _NextlyError({
+      code: "VALIDATION_ERROR",
+      publicMessage: "Validation failed.",
+      publicData: { errors: opts.errors },
+      cause: opts.cause,
+      logContext: opts.logContext
+    });
+  }
+  static conflict(opts) {
+    return new _NextlyError({
+      code: "CONFLICT",
+      publicMessage: opts?.message ?? "The resource has changed since you last loaded it. Please refresh and try again.",
+      cause: opts?.cause,
+      logContext: { reason: opts?.reason, ...opts?.logContext }
+    });
+  }
+  static duplicate(opts) {
+    return new _NextlyError({
+      code: "DUPLICATE",
+      publicMessage: "Resource already exists.",
+      logContext: opts?.logContext
+    });
+  }
+  static rateLimited(opts) {
+    return new _NextlyError({
+      code: "RATE_LIMITED",
+      publicMessage: "Too many requests. Please try again later.",
+      publicData: opts?.retryAfterSeconds !== void 0 ? { retryAfterSeconds: opts.retryAfterSeconds } : void 0,
+      logContext: opts?.logContext
+    });
+  }
+  static internal(opts) {
+    return new _NextlyError({
+      code: "INTERNAL_ERROR",
+      publicMessage: "An unexpected error occurred.",
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  // Accepts an optional `logMessage` override so callers (e.g. the health
+  // route) can record a specific operator narrative ("Health check failed")
+  // while the public message stays canonical per spec §13.8.5.
+  static serviceUnavailable(opts) {
+    return new _NextlyError({
+      code: "SERVICE_UNAVAILABLE",
+      publicMessage: opts?.publicMessage ?? "Service unavailable. Please try again later.",
+      logMessage: opts?.logMessage,
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  /**
+   * Convert a DbError (or arbitrary unknown thrown by the DB layer) to a
+   * NextlyError with a generic public message and rich logContext. Used by
+   * `withDbErrors` for auto-conversion (Pattern A) and by services that
+   * catch DB errors at boundaries (Pattern B). Spec §8.2 mapping table.
+   *
+   * Never leaks DB driver text, constraint names, or table names into
+   * `publicMessage`. All DB context goes into `logContext`. The original
+   * DbError is preserved as `cause`.
+   */
+  static fromDatabaseError(error) {
+    if (isDbError(error)) {
+      const mapping = DB_ERROR_MAPPING[error.kind];
+      const logContext = {
+        dbKind: error.kind,
+        dialect: error.dialect
+      };
+      if (error.code !== void 0) logContext.dbCode = error.code;
+      if (error.meta !== void 0) logContext.meta = error.meta;
+      return new _NextlyError({
+        code: mapping.code,
+        statusCode: mapping.statusCode,
+        publicMessage: mapping.publicMessage,
+        logMessage: "Database error",
+        logContext,
+        cause: error
+      });
+    }
+    return new _NextlyError({
+      code: "INTERNAL_ERROR",
+      statusCode: 500,
+      publicMessage: "An unexpected error occurred.",
+      logMessage: "Non-DbError passed to fromDatabaseError",
+      cause: error instanceof Error ? error : void 0,
+      logContext: error instanceof Error ? void 0 : { value: String(error) }
+    });
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Type guards. Structural rather than `instanceof` so they survive
+  // package-boundary mismatches (one consumer's NextlyError is a
+  // different module instance from another's).
+  // ────────────────────────────────────────────────────────────────────
+  static is(err) {
+    return hasBrand(err);
+  }
+  static isCode(err, code) {
+    return hasBrand(err) && err.code === code;
+  }
+  static isNotFound(err) {
+    return _NextlyError.isCode(err, "NOT_FOUND");
+  }
+  static isValidation(err) {
+    return _NextlyError.isCode(err, "VALIDATION_ERROR");
+  }
+  static isAuthRequired(err) {
+    return _NextlyError.isCode(err, "AUTH_REQUIRED");
+  }
+  static isForbidden(err) {
+    return _NextlyError.isCode(err, "FORBIDDEN");
+  }
+  static isConflict(err) {
+    return _NextlyError.isCode(err, "CONFLICT");
+  }
+  static isRateLimited(err) {
+    return _NextlyError.isCode(err, "RATE_LIMITED");
+  }
+};
+
+// ../nextly/dist/chunk-W77AQUUQ.mjs
+var StorageReadTooLargeError = class extends NextlyError {
+  constructor(path, maxBytes, size) {
+    super({
+      code: "STORAGE_READ_TOO_LARGE",
+      publicMessage: "The stored file is larger than the limit for this read.",
+      logContext: {
+        path,
+        maxBytes,
+        ...size === void 0 ? {} : { size }
+      }
+    });
+    this.path = path;
+    this.maxBytes = maxBytes;
+    this.size = size;
+  }
+};
+
+// ../nextly/dist/chunk-C2VHLQKK.mjs
+var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_READ_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+var DEFAULT_READ_MAX_BYTES = DEFAULT_MAX_RESPONSE_BYTES;
+function resolveReadBounds(options) {
+  return {
+    maxBytes: options?.maxBytes ?? DEFAULT_READ_MAX_BYTES,
+    timeoutMs: options?.timeoutMs ?? DEFAULT_READ_TIMEOUT_MS
+  };
+}
+
+// src/adapter.ts
+function abortAfter(options) {
+  return {
+    abortSignal: AbortSignal.timeout(resolveReadBounds(options).timeoutMs)
+  };
+}
 var S3StorageAdapter = class {
   /**
    * Create a new S3 storage adapter.
@@ -266,6 +743,49 @@ var S3StorageAdapter = class {
       throw error;
     }
   }
+  /**
+   * Read a stored object back as bytes, or `null` when it is not there.
+   *
+   * The contract declares this OPTIONAL and, until now, no adapter supplied
+   * it — so a caller reaching for `adapter.read` got `undefined` and fell
+   * through whatever branch followed. An optional member nothing implements is
+   * a contract that reads as a capability and behaves as an absence.
+   *
+   * BUFFERS rather than streams, because that is the declared return type and
+   * widening it here would make this adapter answer a different question from
+   * its siblings. That bounds what it should be used for: an asset the server
+   * must serve from its own origin — a font file, a small document — rather
+   * than arbitrarily large media, which belongs behind {@link getSignedUrl} or
+   * a public URL. A streaming variant is a separate contract member, not a
+   * quiet change to this one.
+   *
+   * `null` for a missing key rather than a throw, matching
+   * {@link getMetadata}: absence is an ordinary answer about the bucket, while
+   * a credential or network failure is not, so only the first is folded into
+   * the return value.
+   *
+   * @param filePath - Storage path/key
+   * @returns The object's bytes, or `null` when no such key exists
+   */
+  async read(filePath, options) {
+    try {
+      const command = new GetObjectCommand({
+        Bucket: this.resolvedConfig.bucket,
+        Key: filePath
+      });
+      const response = await this.client.send(command, abortAfter(options));
+      if (response.Body === void 0) return Buffer.alloc(0);
+      const cap = resolveReadBounds(options).maxBytes;
+      this.refuseOverCap(filePath, response.ContentLength, cap);
+      return await this.readCapped(filePath, response.Body, cap);
+    } catch (error) {
+      if (error instanceof Error && error.name === "NoSuchBucket") throw error;
+      if (this.isNotFoundError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
   /**
    * Generate signed URL for temporary private file access.
    *
@@ -358,6 +878,61 @@ var S3StorageAdapter = class {
    * @param error - Error to check
    * @returns true if error indicates file not found
    */
+  /**
+   * The object's bytes, refusing once more than `cap` have actually arrived.
+   *
+   * `ContentLength` is OPTIONAL in the SDK's response type, and this adapter
+   * explicitly supports MinIO, R2 and other compatible services — any of which
+   * may omit it or report it wrongly. A preflight check against metadata is
+   * therefore a courtesy that fails OPEN: trusting it alone leaves the cap
+   * unenforced exactly where an unusual backend is involved, which is where a
+   * caller most needs it.
+   *
+   * Counted while consuming, so an oversized body is abandoned partway rather
+   * than after it has all been buffered — the cap exists to bound memory, and
+   * one applied after `transformToByteArray` has already spent it.
+   *
+   * Falls back to buffering when the body is not async-iterable, which the SDK
+   * types permit. Stated rather than hidden: on that path the cap bounds what a
+   * caller RECEIVES rather than what the process allocates.
+   */
+  async readCapped(filePath, body, cap) {
+    const iterable = body;
+    if (typeof iterable[Symbol.asyncIterator] !== "function") {
+      const whole = Buffer.from(await body.transformToByteArray());
+      if (whole.byteLength > cap) {
+        throw new StorageReadTooLargeError(filePath, cap, whole.byteLength);
+      }
+      return whole;
+    }
+    const chunks = [];
+    let received = 0;
+    for await (const chunk of body) {
+      received += chunk.byteLength;
+      if (received > cap) {
+        throw new StorageReadTooLargeError(filePath, cap, received);
+      }
+      chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  /**
+   * Refuse a read whose object is already known to exceed the caller's cap.
+   *
+   * Its own method rather than three conditions inside `read`, because the
+   * decision has nothing to do with the surrounding error handling and reads
+   * as noise there — and because `read`'s branching is the part a reviewer has
+   * to hold in their head to check the absent-versus-unavailable distinction.
+   *
+   * Both `undefined` cases mean "no opinion" and pass: a caller that named no
+   * cap has none, and a store that reported no length gives nothing to compare.
+   * The second is deliberately permissive — refusing an unmeasured object would
+   * reject valid reads whenever S3 omits the header.
+   */
+  refuseOverCap(filePath, declared, cap) {
+    if (cap === void 0 || declared === void 0 || declared <= cap) return;
+    throw new StorageReadTooLargeError(filePath, cap, declared);
+  }
   isNotFoundError(error) {
     if (error && typeof error === "object") {
       const e = error;