@miosa/sdk 3.3.0 → 3.4.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createHmac, timingSafeEqual, randomUUID } from 'crypto';
 import EventEmitter from 'events';
 import { isIP } from 'net';
-import { resolve4 } from 'dns/promises';
+import { lookup } from 'dns/promises';
 import * as http2 from 'http2';
 import { createRequire } from 'module';
 
@@ -30,7 +30,7 @@ var MiosaError = class _MiosaError extends Error {
    * its own backoff policy.
    */
   retryAfterMs;
-  constructor(message, status, code, details, requestId, retryable = defaultRetryable(status), retryAfterMs) {
+  constructor(message, status, code, details, requestId, retryable = defaultRetryable(status), retryAfterMs2) {
     super(message);
     this.name = "MiosaError";
     this.status = status;
@@ -38,7 +38,7 @@ var MiosaError = class _MiosaError extends Error {
     this.details = details;
     this.requestId = requestId;
     this.retryable = retryable;
-    this.retryAfterMs = retryAfterMs;
+    this.retryAfterMs = retryAfterMs2;
   }
   /**
    * @param retryAfterHeaderMs The `Retry-After` header value, already
@@ -54,16 +54,16 @@ var MiosaError = class _MiosaError extends Error {
     const details = nested?.details ?? body5.details ?? (body5.detail || body5.reason ? { detail: body5.detail, reason: body5.reason } : void 0);
     requestId ??= nested?.request_id ?? body5.request_id;
     const retryable = nested?.retryable ?? body5.retryable ?? defaultRetryable(status);
-    const retryAfterMs = nested?.retry_after_ms ?? body5.retry_after_ms ?? retryAfterHeaderMs2;
+    const retryAfterMs2 = nested?.retry_after_ms ?? body5.retry_after_ms ?? retryAfterHeaderMs2;
     const connectError = connectErrorFromCode(code, message, status, details, requestId, retryable);
     const built = connectError ?? (status === 401 || status === 403 ? new AuthError(message, status, code, details, requestId, retryable) : status === 404 ? new NotFoundError(message, code, details, requestId, retryable) : status === 429 ? new RateLimitError(
       message,
       details,
       requestId,
-      retryAfterMs === void 0 ? void 0 : retryAfterMs / 1e3,
+      retryAfterMs2 === void 0 ? void 0 : retryAfterMs2 / 1e3,
       retryable
     ) : status === 402 ? new InsufficientCreditsError(message, details, requestId, retryable) : status >= 400 && status < 500 ? new ValidationError(message, status, code, details, requestId, retryable) : new _MiosaError(message, status, code, details, requestId, retryable));
-    built.retryAfterMs = retryAfterMs;
+    built.retryAfterMs = retryAfterMs2;
     return built;
   }
 };
@@ -185,7 +185,7 @@ var TokenRefreshFailedError = class extends MiosaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "3.3.0";
+var SDK_VERSION = "3.4.0";
 var SDK_USER_AGENT = `@miosa/sdk/${SDK_VERSION}`;
 
 // src/http.ts
@@ -303,7 +303,7 @@ var HttpClient = class {
         clearTimeout(timer);
         if (!response.ok) {
           const requestId = response.headers.get("x-request-id") ?? void 0;
-          const retryAfterMs = retryAfterHeaderMs(
+          const retryAfterMs2 = retryAfterHeaderMs(
             response.headers.get("retry-after")
           );
           let errorBody = {};
@@ -315,7 +315,7 @@ var HttpClient = class {
             response.status,
             errorBody,
             requestId,
-            retryAfterMs
+            retryAfterMs2
           );
           if (error.retryable && attempt < maxRetries) {
             lastError = error;
@@ -11208,24 +11208,36 @@ function sandboxTag(sandboxId) {
   }
   return first.toLowerCase();
 }
+async function lookupAllIpv4(hostname) {
+  const entries = await lookup(hostname, { family: 4, all: true });
+  return entries.map((entry) => entry.address);
+}
+function dedupe(addresses) {
+  return [...new Set(addresses)];
+}
 var DnsAddressResolver = class {
-  constructor(ttlMs = 6e4) {
+  constructor(ttlMs = 6e4, lookupAddresses = lookupAllIpv4) {
     this.ttlMs = ttlMs;
+    this.lookupAddresses = lookupAddresses;
   }
   ttlMs;
+  lookupAddresses;
   cache = /* @__PURE__ */ new Map();
   async resolve(hostname) {
     if (isIP(hostname) !== 0) return [hostname];
     if (hostname === "localhost") return ["127.0.0.1"];
     const cached = this.cache.get(hostname);
     if (cached && cached.expiresAt > Date.now()) return cached.addresses;
-    const addresses = await resolve4(hostname);
+    const addresses = dedupe(await this.lookupAddresses(hostname));
     if (addresses.length === 0) {
       throw new Error(`DnsAddressResolver: ${hostname} resolved to zero A records`);
     }
     this.cache.set(hostname, { addresses, expiresAt: Date.now() + this.ttlMs });
     return addresses;
   }
+  invalidate(hostname) {
+    this.cache.delete(hostname);
+  }
 };
 var StaticAddressResolver = class {
   constructor(table) {
@@ -11282,6 +11294,9 @@ var Http2Transport = class {
   port;
   resolver;
   defaultTimeoutMs;
+  pinAddresses;
+  insecure;
+  dial;
   pools = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     this.defaultSessionsPerAddress = options.defaultSessionsPerAddress ?? DEFAULT_SESSIONS_PER_ADDRESS;
@@ -11289,6 +11304,9 @@ var Http2Transport = class {
     this.port = options.port ?? (this.tls ? 443 : 80);
     this.resolver = options.resolver ?? new DnsAddressResolver();
     this.defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.pinAddresses = options.pinAddresses ?? true;
+    this.insecure = options.insecure ?? false;
+    this.dial = options.connect ?? http2.connect;
   }
   prewarm(regionHostname2, sessionsPerAddress) {
     this.poolFor(regionHostname2, sessionsPerAddress);
@@ -11328,6 +11346,7 @@ var Http2Transport = class {
     try {
       session = await group[cursor];
     } catch (error) {
+      this.noteAddressFailure(regionHostname2, address);
       throw new RunnerConnectError(regionHostname2, address, error);
     }
     if (session.closed || session.destroyed) {
@@ -11336,6 +11355,7 @@ var Http2Transport = class {
       try {
         session = await fresh;
       } catch (error) {
+        this.noteAddressFailure(regionHostname2, address);
         throw new RunnerConnectError(regionHostname2, address, error);
       }
     }
@@ -11366,28 +11386,104 @@ var Http2Transport = class {
     return pool;
   }
   buildPool(regionHostname2, sessionsPerAddress) {
-    const addresses = this.resolver.resolve(regionHostname2);
-    const groups = addresses.then(
-      (resolved) => resolved.map(
-        (address) => (
-          // sessionsPerAddress: 0 is a deliberate "open nothing" (e.g. a
-          // count-only probe).
-          Array.from(
-            { length: sessionsPerAddress },
-            () => markHandled(this.connectSession(regionHostname2, address))
-          )
-        )
-      )
+    const pool = {
+      addresses: this.resolveAddresses(regionHostname2),
+      groups: Promise.resolve([]),
+      nextSlot: /* @__PURE__ */ new Map(),
+      sessionsPerAddress,
+      failed: /* @__PURE__ */ new Set(),
+      rebuilding: void 0
+    };
+    pool.groups = pool.addresses.then(
+      (resolved) => resolved.map((address) => this.openGroup(regionHostname2, address, sessionsPerAddress))
+    );
+    markHandled(pool.addresses);
+    markHandled(pool.groups);
+    return pool;
+  }
+  /**
+   * The addresses this pool pins to. With pinning on, every IPv4 address
+   * the hostname resolves to; with it off, the hostname itself - one entry,
+   * dialled as-is so the OS resolver chooses.
+   */
+  resolveAddresses(regionHostname2) {
+    return this.pinAddresses ? this.resolver.resolve(regionHostname2) : Promise.resolve([regionHostname2]);
+  }
+  /**
+   * Opens `sessionsPerAddress` sessions against one address, in parallel.
+   * sessionsPerAddress: 0 is a deliberate "open nothing" (e.g. a count-only
+   * probe).
+   */
+  openGroup(regionHostname2, address, sessionsPerAddress) {
+    return Array.from(
+      { length: sessionsPerAddress },
+      () => markHandled(this.connectSession(regionHostname2, address))
     );
-    markHandled(addresses);
-    markHandled(groups);
-    return { addresses, groups, nextSlot: /* @__PURE__ */ new Map() };
+  }
+  /** Closes a session slot once it connects, ignoring one that never did. */
+  closeSlot(slot) {
+    slot.then((session) => {
+      if (!session.closed) session.close();
+    }).catch(() => void 0);
+  }
+  /**
+   * A session pinned to `address` failed to connect. Mark that address's
+   * group for reopening and re-resolve in the background (single-flight),
+   * so one dead address never costs every concurrent failure its own DNS
+   * lookup. Never blocks or fails the request that is already on its way
+   * out - the caller retries another index (C6's next-IP retry).
+   */
+  noteAddressFailure(regionHostname2, address) {
+    if (!this.pinAddresses) return;
+    const pool = this.pools.get(regionHostname2);
+    if (!pool) return;
+    pool.failed.add(address);
+    this.resolver.invalidate?.(regionHostname2);
+    if (pool.rebuilding) return;
+    pool.rebuilding = this.rebuildPool(regionHostname2, pool).finally(() => {
+      pool.rebuilding = void 0;
+    });
+  }
+  /**
+   * Re-resolves `regionHostname` and redistributes the pool over the fresh
+   * addresses: the failed address's sessions are dropped and reopened, a
+   * newly advertised address gets a group of its own, an address DNS no
+   * longer lists loses its sessions, and every healthy address keeps the
+   * sessions it already has - so a failure on one host never costs the rest
+   * their warm connections.
+   */
+  async rebuildPool(regionHostname2, pool) {
+    const failed = new Set(pool.failed);
+    pool.failed.clear();
+    const resolved = await this.resolveAddresses(regionHostname2).catch(() => void 0);
+    if (!resolved) {
+      for (const address of failed) pool.failed.add(address);
+      return;
+    }
+    const previous = await pool.addresses.catch(() => []);
+    const previousGroups = await pool.groups.catch(
+      () => []
+    );
+    const groups = resolved.map((address) => {
+      const index = previous.indexOf(address);
+      const reusable = index >= 0 && !failed.has(address) ? previousGroups[index] : void 0;
+      if (reusable) return reusable;
+      for (const slot of previousGroups[index] ?? []) this.closeSlot(slot);
+      return this.openGroup(regionHostname2, address, pool.sessionsPerAddress);
+    });
+    previous.forEach((address, index) => {
+      if (resolved.includes(address)) return;
+      for (const slot of previousGroups[index] ?? []) this.closeSlot(slot);
+    });
+    pool.addresses = Promise.resolve(resolved);
+    pool.groups = Promise.resolve(groups);
+    pool.nextSlot.clear();
   }
   connectSession(regionHostname2, address) {
     return new Promise((resolve, reject) => {
       const authority = `${this.tls ? "https" : "http"}://${address}:${this.port}`;
-      const connectOptions = this.tls ? { servername: regionHostname2 } : {};
-      const session = http2.connect(authority, connectOptions);
+      const connectOptions = this.tls ? { servername: regionHostname2, rejectUnauthorized: !this.insecure } : {};
+      const session = this.dial(authority, connectOptions);
       const onError = (error) => {
         session.destroy();
         reject(error);
@@ -11560,6 +11656,8 @@ var Http3Transport = class {
   connectTimeoutMs;
   insecure;
   port;
+  pinAddresses;
+  dial;
   pools = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     const native = loadNative();
@@ -11573,6 +11671,8 @@ var Http3Transport = class {
     this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     this.insecure = options.insecure ?? false;
     this.port = options.port ?? 443;
+    this.pinAddresses = options.pinAddresses ?? true;
+    this.dial = options.connect ?? ((address, servername, port, insecure, timeoutMs) => this.native.h3Connect(address, servername, port, insecure, timeoutMs));
   }
   prewarm(regionHostname2, sessionsPerAddress) {
     this.poolFor(regionHostname2, sessionsPerAddress);
@@ -11618,6 +11718,7 @@ var Http3Transport = class {
     try {
       handle = await group[cursor];
     } catch (error) {
+      this.noteAddressFailure(regionHostname2, address);
       throw new RunnerConnectError(regionHostname2, address, error);
     }
     const reconnect = () => {
@@ -11652,21 +11753,99 @@ var Http3Transport = class {
     return pool;
   }
   buildPool(regionHostname2, sessionsPerAddress) {
-    const addresses = this.resolver.resolve(regionHostname2);
-    const groups = addresses.then(
-      (resolved) => resolved.map(
-        (address) => Array.from(
-          { length: sessionsPerAddress },
-          () => markHandled2(this.connectSession(regionHostname2, address))
-        )
-      )
+    const pool = {
+      addresses: this.resolveAddresses(regionHostname2),
+      groups: Promise.resolve([]),
+      nextSlot: /* @__PURE__ */ new Map(),
+      sessionsPerAddress,
+      failed: /* @__PURE__ */ new Set(),
+      rebuilding: void 0
+    };
+    pool.groups = pool.addresses.then(
+      (resolved) => resolved.map((address) => this.openGroup(regionHostname2, address, sessionsPerAddress))
     );
-    markHandled2(addresses);
-    markHandled2(groups);
-    return { addresses, groups, nextSlot: /* @__PURE__ */ new Map() };
+    markHandled2(pool.addresses);
+    markHandled2(pool.groups);
+    return pool;
+  }
+  /**
+   * The addresses this pool pins to. With pinning on, every IPv4 address
+   * the hostname resolves to. With it off, the hostname is resolved once
+   * and only its first address is kept - one target, chosen by the OS
+   * resolver, which is the closest this transport can get to HTTP/2's
+   * hostname dial: the native addon takes a literal socket address, never
+   * a hostname.
+   */
+  async resolveAddresses(regionHostname2) {
+    if (this.pinAddresses) return this.resolver.resolve(regionHostname2);
+    const [first] = await this.resolver.resolve(regionHostname2);
+    if (!first) {
+      throw new Error(`Http3Transport: ${regionHostname2} resolved to zero addresses`);
+    }
+    return [first];
+  }
+  /** Opens `sessionsPerAddress` connections against one address, in parallel. */
+  openGroup(regionHostname2, address, sessionsPerAddress) {
+    return Array.from(
+      { length: sessionsPerAddress },
+      () => markHandled2(this.connectSession(regionHostname2, address))
+    );
+  }
+  /** Closes a connection slot once it connects, ignoring one that never did. */
+  closeSlot(slot) {
+    slot.then((handle) => this.native.h3Close(handle)).catch(() => void 0);
+  }
+  /**
+   * A connection pinned to `address` failed to connect. Mark that address's
+   * group for reopening and re-resolve in the background (single-flight),
+   * so one dead address never costs every concurrent failure its own DNS
+   * lookup. Never blocks or fails the request already on its way out.
+   */
+  noteAddressFailure(regionHostname2, address) {
+    if (!this.pinAddresses) return;
+    const pool = this.pools.get(regionHostname2);
+    if (!pool) return;
+    pool.failed.add(address);
+    this.resolver.invalidate?.(regionHostname2);
+    if (pool.rebuilding) return;
+    pool.rebuilding = this.rebuildPool(regionHostname2, pool).finally(() => {
+      pool.rebuilding = void 0;
+    });
+  }
+  /**
+   * Re-resolves `regionHostname` and redistributes the pool over the fresh
+   * addresses: the failed address's connections are dropped and reopened, a
+   * newly advertised address gets a group of its own, an address DNS no
+   * longer lists loses its connections, and every healthy address keeps the
+   * connections it already has.
+   */
+  async rebuildPool(regionHostname2, pool) {
+    const failed = new Set(pool.failed);
+    pool.failed.clear();
+    const resolved = await this.resolveAddresses(regionHostname2).catch(() => void 0);
+    if (!resolved) {
+      for (const address of failed) pool.failed.add(address);
+      return;
+    }
+    const previous = await pool.addresses.catch(() => []);
+    const previousGroups = await pool.groups.catch(() => []);
+    const groups = resolved.map((address) => {
+      const index = previous.indexOf(address);
+      const reusable = index >= 0 && !failed.has(address) ? previousGroups[index] : void 0;
+      if (reusable) return reusable;
+      for (const slot of previousGroups[index] ?? []) this.closeSlot(slot);
+      return this.openGroup(regionHostname2, address, pool.sessionsPerAddress);
+    });
+    previous.forEach((address, index) => {
+      if (resolved.includes(address)) return;
+      for (const slot of previousGroups[index] ?? []) this.closeSlot(slot);
+    });
+    pool.addresses = Promise.resolve(resolved);
+    pool.groups = Promise.resolve(groups);
+    pool.nextSlot.clear();
   }
   connectSession(regionHostname2, address) {
-    return this.native.h3Connect(address, regionHostname2, this.port, this.insecure, this.connectTimeoutMs);
+    return this.dial(address, regionHostname2, this.port, this.insecure, this.connectTimeoutMs);
   }
   async sendRequest(regionHostname2, address, authority, path, handle, init, reconnect) {
     const timeoutMs = init.timeoutMs ?? this.defaultTimeoutMs;
@@ -11694,6 +11873,7 @@ var Http3Transport = class {
       try {
         fresh = await reconnect();
       } catch (reconnectError) {
+        this.noteAddressFailure(regionHostname2, address);
         throw new RunnerConnectError(regionHostname2, address, reconnectError);
       }
       return attempt(fresh);
@@ -11722,7 +11902,7 @@ async function* singleChunk(body5) {
 // src/runner/transport-factory.ts
 function createBestTransport(options = {}) {
   const http3 = detectHttp3Support();
-  if (!http3.available) {
+  if (!http3.available || options.raceHttp3 !== true) {
     return { transport: new Http2Transport(options.http2), http3 };
   }
   const transport = new RacingTransport(new Http2Transport(options.http2), new Http3Transport(options.http3));
@@ -11830,6 +12010,16 @@ var RunnerError = class _RunnerError extends Error {
   get isBusy() {
     return this.code === "runtime_busy" || this.code === "feed_stale";
   }
+  /**
+   * `429 rate_limited`: the key's own window on this runner has no room.
+   *
+   * Separate from `isBusy`, which means this runner's admission is full for
+   * everyone. The limiter counts per key per runner, so a refusal here says
+   * nothing about the next address, and `createSandbox` may try that one.
+   */
+  get isRateLimited() {
+    return this.code === "rate_limited";
+  }
   /** C2: the runner doesn't serve this create shape at all - send it to api.miosa.ai instead. */
   get isUnsupportedRequest() {
     return this.code === "RUNNER_UNSUPPORTED_REQUEST";
@@ -11889,6 +12079,18 @@ function createSupportedByRunner(params) {
   const isNonXs = size !== void 0 && size !== "xs";
   return !(hasTemplate || hasSnapshot || hasCwd || isPersistent || isNonXs);
 }
+var RATE_LIMIT_RETRY_CAP_MS = 250;
+function retryAfterMs(headers, capMs = RATE_LIMIT_RETRY_CAP_MS) {
+  const raw = headers["retry-after"] ?? headers["Retry-After"];
+  if (raw === void 0) return 0;
+  const seconds = Number(raw.trim());
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1e3, capMs);
+  const at = Date.parse(raw);
+  return Number.isNaN(at) ? 0 : Math.min(Math.max(0, at - Date.now()), capMs);
+}
+function sleep9(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var RunnerClient = class {
   region;
   hostname;
@@ -11901,13 +12103,26 @@ var RunnerClient = class {
   addressIndexByTag = /* @__PURE__ */ new Map();
   /** sandbox id -> tag, set only once a 421 corrects the id-derived guess. */
   correctedTag = /* @__PURE__ */ new Map();
+  /**
+   * Rotating start address for creates, so a cold burst spreads over every
+   * resolved runner address instead of all of it landing on address 0.
+   * Advanced once per create; the retry on `429 runtime_busy`/connect
+   * failure still walks the other addresses from there.
+   */
+  createCursor = 0;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.region = options.region ?? regionFromApiKey(options.apiKey);
     this.baseDomain = options.baseDomain ?? DEFAULT_RUNNER_BASE_DOMAIN;
     this.hostname = regionHostname(this.region, this.baseDomain);
     this.sessionsPerAddress = options.sessionsPerAddress ?? DEFAULT_SESSIONS_PER_ADDRESS3;
-    this.transport = options.transport ?? createBestTransport().transport;
+    this.transport = options.transport ?? createBestTransport({
+      raceHttp3: options.http3,
+      ...options.pinAddresses === void 0 ? {} : {
+        http2: { pinAddresses: options.pinAddresses },
+        http3: { pinAddresses: options.pinAddresses }
+      }
+    }).transport;
     this.fallbackCreate = options.fallbackCreate;
     this.transport.prewarm(this.hostname, this.sessionsPerAddress);
     void this.discoverTags();
@@ -11941,8 +12156,12 @@ var RunnerClient = class {
     if (n === 0) {
       throw new Error(`RunnerClient: no runner addresses for ${this.hostname}`);
     }
+    const start = this.createCursor % n;
+    this.createCursor = (this.createCursor + 1) % n;
     let lastError;
-    for (let attempt = 0; attempt < n; attempt++) {
+    let rateLimitRetries = 0;
+    for (let offset = 0; offset < n; offset++) {
+      const attempt = (start + offset) % n;
       let res;
       try {
         res = await this.transport.request(this.hostname, attempt, this.hostname, "/api/v1/sandboxes", {
@@ -11963,6 +12182,14 @@ var RunnerClient = class {
           lastError = error;
           continue;
         }
+        if (error.isRateLimited) {
+          if (rateLimitRetries >= 1) throw error;
+          rateLimitRetries += 1;
+          lastError = error;
+          const waitMs = retryAfterMs(res.headers);
+          if (waitMs > 0) await sleep9(waitMs);
+          continue;
+        }
         throw error;
       }
       const data = res.body ? JSON.parse(res.body) : {};
@@ -12512,6 +12739,7 @@ var Miosa = class {
       apiKey: credential,
       ...runnerRegion ? { region: runnerRegion } : {},
       ...config.runner?.baseDomain ? { baseDomain: config.runner.baseDomain } : {},
+      ...config.runner?.pinAddresses === void 0 ? {} : { pinAddresses: config.runner.pinAddresses },
       ...config.tenant ? { tenant: config.tenant } : {},
       // C2: creates the runner doesn't serve (template/image/snapshot/
       // cwd/persistent/non-xs) go through the existing control-plane