@everystack/cli 0.3.6 → 0.3.8

package/README.md

@@ -103,6 +103,33 @@ const storage = createStorage({
 });
 ```
 
+The S3 client is **bounded by default** so a single call can never hang: a
+connect timeout (3s), a per-request timeout (10s), bounded retries (3 attempts),
+and a capped `list()` (paged with a page backstop). This matters most for the
+observability rollup — an unbounded client under an S3 503 storm blocks until
+the Lambda's own timeout, and each hung invocation pins a concurrency slot, so
+it can drain the account pool and starve the app it observes.
+
+Tune per-field via `options`, or override the timeouts/retries by env var
+without a code change (env is handy for turning a knob on a live Lambda):
+
+```typescript
+const storage = createStorage({
+  type: 's3',
+  bucket: 'my-updates-bucket',
+  region: 'us-east-1',
+  options: {
+    connectionTimeoutMs: 3000, // env: EVERYSTACK_S3_CONNECT_TIMEOUT_MS
+    requestTimeoutMs: 10000,    // env: EVERYSTACK_S3_REQUEST_TIMEOUT_MS
+    maxAttempts: 3,             // env: EVERYSTACK_S3_MAX_ATTEMPTS
+    listMaxKeys: 1000,          // keys per ListObjectsV2 page
+    listMaxPages: 1000,         // hard backstop before list() truncates (warns)
+  },
+});
+```
+
+Precedence per field: explicit `options` > env var > default.
+
 ### Custom Adapter
 
 Implement the `StorageAdapter` interface:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -87,7 +87,7 @@
     "@aws-sdk/s3-request-presigner": "3.1053.0",
     "drizzle-orm": "0.41.0",
     "expo-updates": "55.0.21",
-    "react": "19.2.6",
+    "react": "19.2.0",
     "react-native": "0.83.6"
   },
   "peerDependenciesMeta": {
@@ -139,7 +139,7 @@
     "@types/react": "19.2.14",
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
-    "react": "19.2.6",
+    "react": "19.2.0",
     "ts-jest": "29.4.9"
   },
   "scripts": {

package/src/env.js

@@ -30,12 +30,25 @@ const fs_1 = __importDefault(require("fs"));
 /**
  * Detect the current build surface from environment signals.
  *
- * EAS_BUILD / EAS_BUILD_PLATFORM  -> native (EAS native build)
- * EAS_UPDATE                      -> native (EAS OTA update)
- * EVERYSTACK_UPDATE               -> web    (everystack update)
- * none of the above               -> local  (pnpm dev)
+ * EVERYSTACK_SURFACE=native|web|local  -> explicit override (declared surface)
+ * EAS_BUILD / EAS_BUILD_PLATFORM       -> native (EAS native build)
+ * EAS_UPDATE                           -> native (EAS OTA update)
+ * EVERYSTACK_UPDATE                    -> web    (everystack update)
+ * none of the above                    -> local  (pnpm dev)
+ *
+ * `EVERYSTACK_SURFACE` is the honest way to pin the surface for an `eas build`.
+ * EAS's own `EAS_BUILD` marker exists only on the build worker, not during the
+ * local config-resolution phase where `eas build` first evaluates app.config.js
+ * (to compute the fingerprint before upload). But EAS injects a build profile's
+ * `env` block into process.env during BOTH phases, so declaring
+ * `EVERYSTACK_SURFACE: "native"` in eas.json pins the surface everywhere without
+ * impersonating an EAS-internal variable.
  */
 function detectSurface() {
+    const explicit = process.env.EVERYSTACK_SURFACE;
+    if (explicit === 'native' || explicit === 'web' || explicit === 'local') {
+        return explicit;
+    }
     if (process.env.EAS_BUILD || process.env.EAS_BUILD_PLATFORM || process.env.EAS_UPDATE) {
         return 'native';
     }
@@ -171,7 +184,8 @@ function load(options) {
         }
         else {
             throw new Error(`[everystack/env] Surface resolved to 'local' but ENVIRONMENT=${process.env.ENVIRONMENT}. `
-                + "Deployable builds must run under 'everystack update' (EVERYSTACK_UPDATE) or EAS (EAS_BUILD). "
+                + 'Declare the build surface: set EVERYSTACK_SURFACE=native (EAS build) or =web in the '
+                + "eas.json build profile env, or run under 'everystack update'. "
                 + 'Refusing to bundle with the local tier set. Set EVERYSTACK_SURFACE=local to override for debugging.');
         }
     }

package/src/env.ts

@@ -47,12 +47,25 @@ export type Surface = 'local' | 'native' | 'web';
 /**
  * Detect the current build surface from environment signals.
  *
- * EAS_BUILD / EAS_BUILD_PLATFORM  -> native (EAS native build)
- * EAS_UPDATE                      -> native (EAS OTA update)
- * EVERYSTACK_UPDATE               -> web    (everystack update)
- * none of the above               -> local  (pnpm dev)
+ * EVERYSTACK_SURFACE=native|web|local  -> explicit override (declared surface)
+ * EAS_BUILD / EAS_BUILD_PLATFORM       -> native (EAS native build)
+ * EAS_UPDATE                           -> native (EAS OTA update)
+ * EVERYSTACK_UPDATE                    -> web    (everystack update)
+ * none of the above                    -> local  (pnpm dev)
+ *
+ * `EVERYSTACK_SURFACE` is the honest way to pin the surface for an `eas build`.
+ * EAS's own `EAS_BUILD` marker exists only on the build worker, not during the
+ * local config-resolution phase where `eas build` first evaluates app.config.js
+ * (to compute the fingerprint before upload). But EAS injects a build profile's
+ * `env` block into process.env during BOTH phases, so declaring
+ * `EVERYSTACK_SURFACE: "native"` in eas.json pins the surface everywhere without
+ * impersonating an EAS-internal variable.
  */
 export function detectSurface(): Surface {
+  const explicit = process.env.EVERYSTACK_SURFACE;
+  if (explicit === 'native' || explicit === 'web' || explicit === 'local') {
+    return explicit;
+  }
   if (process.env.EAS_BUILD || process.env.EAS_BUILD_PLATFORM || process.env.EAS_UPDATE) {
     return 'native';
   }
@@ -207,7 +220,8 @@ export function load(options?: { path?: string }): { extra: Record<string, strin
     } else {
       throw new Error(
         `[everystack/env] Surface resolved to 'local' but ENVIRONMENT=${process.env.ENVIRONMENT}. `
-        + "Deployable builds must run under 'everystack update' (EVERYSTACK_UPDATE) or EAS (EAS_BUILD). "
+        + 'Declare the build surface: set EVERYSTACK_SURFACE=native (EAS build) or =web in the '
+        + "eas.json build profile env, or run under 'everystack update'. "
         + 'Refusing to bundle with the local tier set. Set EVERYSTACK_SURFACE=local to override for debugging.'
       );
     }

package/src/storage/index.ts

@@ -1,3 +1,5 @@
+import type { S3StorageOptions } from './s3';
+
 export interface StorageAdapter {
   put(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<void>;
   get(key: string): Promise<{ data: Buffer; contentType: string } | null>;
@@ -32,7 +34,18 @@ export interface StorageAdapter {
 
 export type StorageOptions =
   | { type: 'filesystem'; directory: string }
-  | { type: 's3'; bucket: string; region?: string; endpoint?: string };
+  | {
+      type: 's3';
+      bucket: string;
+      region?: string;
+      endpoint?: string;
+      /**
+       * Bound the S3 client's failure modes (connect/request timeouts, retries,
+       * list caps). Every field defaults to a safe bound; env vars override too.
+       * See {@link S3StorageOptions}.
+       */
+      options?: S3StorageOptions;
+    };
 
 export async function createStorage(options: StorageOptions): Promise<StorageAdapter> {
   if (options.type === 'filesystem') {
@@ -40,8 +53,8 @@ export async function createStorage(options: StorageOptions): Promise<StorageAda
     return new FilesystemStorageAdapter(options.directory);
   }
   const { S3StorageAdapter } = await import('./s3');
-  return new S3StorageAdapter(options.bucket, options.region, options.endpoint);
+  return new S3StorageAdapter(options.bucket, options.region, options.endpoint, options.options);
 }
 
 export { FilesystemStorageAdapter } from './filesystem';
-export { S3StorageAdapter } from './s3';
+export { S3StorageAdapter, type S3StorageOptions } from './s3';

package/src/storage/s3.ts

@@ -1,15 +1,58 @@
 import type { StorageAdapter } from './index';
 
+/**
+ * Tuning for the S3 client's failure modes. Every value is bounded by default so
+ * a single call can never hang: under an S3 503 SlowDown storm an unbounded
+ * client blocks until the Lambda's own timeout (60s), and because each hung
+ * invocation pins a concurrency slot, the observability rollup can drain the
+ * whole account pool and starve the app it observes. Bounded here, a stuck call
+ * fails fast instead. Overridable per-field, then by env (so ops can tighten a
+ * live Lambda without a code redeploy), then these defaults.
+ */
+export interface S3StorageOptions {
+  /** TCP connect timeout, ms. Env: EVERYSTACK_S3_CONNECT_TIMEOUT_MS. */
+  connectionTimeoutMs?: number;
+  /** Socket-idle timeout for a single request, ms. Env: EVERYSTACK_S3_REQUEST_TIMEOUT_MS. */
+  requestTimeoutMs?: number;
+  /** Total attempts per call (1 + retries). Env: EVERYSTACK_S3_MAX_ATTEMPTS. */
+  maxAttempts?: number;
+  /** Keys per ListObjectsV2 page (S3 caps this at 1000). */
+  listMaxKeys?: number;
+  /** Hard backstop on pages a single list() will walk before truncating (warns). */
+  listMaxPages?: number;
+}
+
+function envInt(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
 export class S3StorageAdapter implements StorageAdapter {
   private bucket: string;
   private region: string;
   private endpoint?: string;
   private client: any;
 
-  constructor(bucket: string, region?: string, endpoint?: string) {
+  private readonly connectionTimeoutMs: number;
+  private readonly requestTimeoutMs: number;
+  private readonly maxAttempts: number;
+  private readonly listMaxKeys: number;
+  private readonly listMaxPages: number;
+
+  constructor(bucket: string, region?: string, endpoint?: string, options: S3StorageOptions = {}) {
     this.bucket = bucket;
     this.region = region || 'us-east-1';
     this.endpoint = endpoint;
+
+    this.connectionTimeoutMs =
+      options.connectionTimeoutMs ?? envInt('EVERYSTACK_S3_CONNECT_TIMEOUT_MS') ?? 3000;
+    this.requestTimeoutMs =
+      options.requestTimeoutMs ?? envInt('EVERYSTACK_S3_REQUEST_TIMEOUT_MS') ?? 10000;
+    this.maxAttempts = options.maxAttempts ?? envInt('EVERYSTACK_S3_MAX_ATTEMPTS') ?? 3;
+    this.listMaxKeys = options.listMaxKeys ?? 1000;
+    this.listMaxPages = options.listMaxPages ?? 1000;
   }
 
   private async getClient(): Promise<any> {
@@ -17,6 +60,15 @@ export class S3StorageAdapter implements StorageAdapter {
       const { S3Client } = await import('@aws-sdk/client-s3');
       this.client = new S3Client({
         region: this.region,
+        // Bounded retries — the SDK default (3) is fine, but pin it so a config
+        // drift can't reintroduce unbounded blocking under throttling.
+        maxAttempts: this.maxAttempts,
+        // Connect + per-request timeouts. Without these a call can block forever
+        // on a stalled socket (the 60s-hang class the rollup outage rode in on).
+        requestHandler: {
+          connectionTimeout: this.connectionTimeoutMs,
+          requestTimeout: this.requestTimeoutMs,
+        },
         ...(this.endpoint ? { endpoint: this.endpoint, forcePathStyle: true } : {}),
       });
     }
@@ -136,11 +188,13 @@ export class S3StorageAdapter implements StorageAdapter {
     const client = await this.getClient();
     const keys: string[] = [];
     let continuationToken: string | undefined;
+    let pages = 0;
 
     do {
       const response = await client.send(new ListObjectsV2Command({
         Bucket: this.bucket,
         Prefix: prefix,
+        MaxKeys: this.listMaxKeys,
         ContinuationToken: continuationToken,
       }));
       if (response.Contents) {
@@ -149,6 +203,17 @@ export class S3StorageAdapter implements StorageAdapter {
         }
       }
       continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+      pages += 1;
+      // Backstop: a prefix that walks past the page cap is almost always a sign
+      // the rollup's per-hour debounce isn't engaged (one object → one invoke).
+      // Truncate loudly rather than let a single list() run unbounded.
+      if (continuationToken && pages >= this.listMaxPages) {
+        console.warn(
+          `[s3] list('${prefix}') hit the ${this.listMaxPages}-page cap at ${keys.length} keys; truncating. ` +
+            `A prefix this large usually means the observability rollup is being invoked per-object instead of per-hour.`,
+        );
+        break;
+      }
     } while (continuationToken);
 
     return keys;