@miosa/sdk 3.3.1 → 3.4.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as ws from 'ws';
 import EventEmitter from 'node:events';
+import * as http2 from 'node:http2';
 
 interface RequestOptions {
     method?: string;
@@ -2243,6 +2244,13 @@ interface MiosaClientConfig {
         region?: string;
         /** Overrides `miosa.ai` - for self-hosted / test deployments. */
         baseDomain?: string;
+        /**
+         * Pin each runner session group to one resolved IPv4 address, so
+         * `run-<region>.miosa.ai`'s several A records are all used. Set `false`
+         * to dial the hostname and let the OS resolver choose instead.
+         * Defaults to `true`.
+         */
+        pinAddresses?: boolean;
     };
 }
 
@@ -8855,8 +8863,22 @@ interface RunnerClientOptions {
     tenant?: string;
     /** Sessions opened per resolved region address. C6 default: 8. */
     sessionsPerAddress?: number;
+    /**
+     * Pin each session group to one resolved runner address (C6), so creates
+     * spread over every host behind `run-<region>.miosa.ai`. Set `false` to
+     * dial the hostname and let the OS resolver choose instead. Defaults to
+     * `true`; only consulted when `transport` is not injected.
+     */
+    pinAddresses?: boolean;
     /** Injectable for tests; defaults to the best available transport. */
     transport?: RunnerTransport;
+    /**
+     * Race HTTP/3 against HTTP/2 per region host. Default false: HTTP/2 only.
+     * See transport-factory.ts for why the race is opt-in - on a cold burst the
+     * promotion can land requests on HTTP/3 sessions that are not yet carrying
+     * traffic, which costs several times what HTTP/2 does.
+     */
+    http3?: boolean;
     /**
      * Called for a create the runner doesn't serve (C2: template, image,
      * snapshot, cwd, persistent, non-xs shapes) - wired by `Miosa` to
@@ -9003,6 +9025,13 @@ declare class RunnerClient {
     private readonly addressIndexByTag;
     /** sandbox id -> tag, set only once a 421 corrects the id-derived guess. */
     private readonly correctedTag;
+    /**
+     * 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.
+     */
+    private createCursor;
     constructor(options: RunnerClientOptions);
     get protocol(): RunnerProtocol;
     /** The tag a 421 has corrected sandboxId to, if any. */
@@ -9510,17 +9539,32 @@ declare function sandboxTag(sandboxId: string): string;
 /** Resolves a hostname to the list of IP addresses it should be reached at. */
 interface AddressResolver {
     resolve(hostname: string): Promise<string[]>;
+    /**
+     * Forgets anything cached for `hostname`, so the next `resolve` asks the
+     * OS resolver again. The transports call this after a per-address connect
+     * failure: a runner host that has moved, or whose address has gone away,
+     * is re-resolved rather than retried at a stale address for the rest of
+     * the cache window. Optional - a resolver with nothing to cache omits it.
+     */
+    invalidate?(hostname: string): void;
 }
+/** Resolves a hostname straight to its list of IPv4 addresses, in resolver order. */
+type AddressLookup = (hostname: string) => Promise<string[]>;
 /**
- * Default resolver: plain DNS A-record lookup, with IP literals and
- * `localhost` passed through unchanged so tests and self-hosted runners
- * can point the transport straight at a fixed address without a resolver.
+ * Default resolver: every IPv4 address of the hostname, cached for a short
+ * TTL (60 s - the runners' advertised A-record TTL) so a burst of requests
+ * resolves once instead of hitting the resolver per request. IP literals
+ * and `localhost` are passed through unchanged so tests and self-hosted
+ * runners can point the transport straight at a fixed address without a
+ * resolver.
  */
 declare class DnsAddressResolver implements AddressResolver {
     private readonly ttlMs;
+    private readonly lookupAddresses;
     private readonly cache;
-    constructor(ttlMs?: number);
+    constructor(ttlMs?: number, lookupAddresses?: AddressLookup);
     resolve(hostname: string): Promise<string[]>;
+    invalidate(hostname: string): void;
 }
 /** A fixed-table resolver, for tests and for pinning to known runner IPs (C1). */
 declare class StaticAddressResolver implements AddressResolver {
@@ -9551,8 +9595,23 @@ declare class StaticAddressResolver implements AddressResolver {
  * coalescing: the cert covers `run-<region>.miosa.ai` and
  * `*.run-<region>.miosa.ai`, and a per-host name's one A record is the
  * same IP already in this pool - see transport.ts's doc comment).
+ *
+ * Pinning is what makes the dial target explicit: the hostname is resolved
+ * once, and every session dials its own resolved IP while SNI and the
+ * HTTP/2 `:authority` stay the hostname, so a name with several A records
+ * spreads over all of them deterministically instead of wherever the OS
+ * resolver happens to point. `pinAddresses: false` turns this off and dials
+ * the hostname itself, letting the OS resolver choose (one address, the
+ * pre-pinning behaviour). A per-address connect failure drops that
+ * address's sessions, invalidates the resolver's cache and re-resolves, so
+ * a host that has moved is not retried at a stale address.
  */
 
+/**
+ * The dial itself, injectable so tests can observe (and selectively fail)
+ * which address a session is opened against without a real socket.
+ */
+type Http2Connector = (authority: string, options: http2.SecureClientSessionOptions) => http2.ClientHttp2Session;
 interface Http2TransportOptions {
     /** Sessions opened per address when no explicit count is given. C6 default: 8. */
     defaultSessionsPerAddress?: number;
@@ -9562,6 +9621,17 @@ interface Http2TransportOptions {
     resolver?: AddressResolver;
     /** Default per-request timeout when the caller doesn't set one. */
     defaultTimeoutMs?: number;
+    /**
+     * Pin every session group to one resolved IPv4 address (C6), so a name
+     * with several A records is dialled at all of them deliberately. Set
+     * `false` to dial the hostname itself and let the OS resolver pick - the
+     * pre-pinning behaviour, one address only. Defaults to `true`.
+     */
+    pinAddresses?: boolean;
+    /** Skips TLS certificate verification. Test-only - never set true in production. */
+    insecure?: boolean;
+    /** Injectable for tests; defaults to `node:http2`'s connect. */
+    connect?: Http2Connector;
 }
 declare class Http2Transport implements RunnerTransport {
     readonly protocol: "h2";
@@ -9570,7 +9640,16 @@ declare class Http2Transport implements RunnerTransport {
     private readonly port;
     private readonly resolver;
     private readonly defaultTimeoutMs;
+    private readonly pinAddresses;
+    private readonly insecure;
+    private readonly dial;
     private readonly pools;
+    /**
+     * Requests in flight per session. A pooled session is unref'd while idle so
+     * a process that only imported the client (or finished its last request)
+     * still exits; it is ref'd again for exactly as long as it carries a request.
+     */
+    private readonly inFlight;
     constructor(options?: Http2TransportOptions);
     prewarm(regionHostname: string, sessionsPerAddress?: number): void;
     addressCount(regionHostname: string): Promise<number>;
@@ -9582,7 +9661,40 @@ declare class Http2Transport implements RunnerTransport {
     close(): Promise<void>;
     private poolFor;
     private buildPool;
+    /**
+     * 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.
+     */
+    private resolveAddresses;
+    /**
+     * Opens `sessionsPerAddress` sessions against one address, in parallel.
+     * sessionsPerAddress: 0 is a deliberate "open nothing" (e.g. a count-only
+     * probe).
+     */
+    private openGroup;
+    /** Closes a session slot once it connects, ignoring one that never did. */
+    private closeSlot;
+    /**
+     * 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).
+     */
+    private noteAddressFailure;
+    /**
+     * 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.
+     */
+    private rebuildPool;
     private connectSession;
+    private retain;
+    private release;
     private sendRequest;
     private sendStreamRequest;
 }
@@ -9611,6 +9723,12 @@ interface Http3Availability {
 declare function detectHttp3Support(): Http3Availability;
 /** Exposed for tests - clears the cached load result and availability. */
 declare function resetHttp3DetectionCache(): void;
+/**
+ * The connection handshake, injectable so tests can observe (and
+ * selectively fail) which address a connection is opened against without a
+ * native QUIC listener.
+ */
+type Http3Connector = (address: string, servername: string, port: number, insecure: boolean, connectTimeoutMs: number) => Promise<number>;
 interface Http3TransportOptions {
     /** Sessions opened per address when no explicit count is given. C6: 4. */
     defaultSessionsPerAddress?: number;
@@ -9626,6 +9744,17 @@ interface Http3TransportOptions {
     /** Skips certificate verification. Test-only - never set true in production. */
     insecure?: boolean;
     port?: number;
+    /**
+     * Pin every connection group to one resolved IPv4 address (C6), so a name
+     * with several A records is dialled at all of them deliberately. Set
+     * `false` to use only the hostname's first resolved address and let the
+     * OS resolver pick which that is - one target, the pre-pinning shape (the
+     * native addon dials a literal address, so a hostname cannot be passed
+     * through here). Defaults to `true`.
+     */
+    pinAddresses?: boolean;
+    /** Injectable for tests; defaults to the native addon's connect. */
+    connect?: Http3Connector;
 }
 declare class Http3Transport implements RunnerTransport {
     readonly protocol: "h3";
@@ -9636,6 +9765,8 @@ declare class Http3Transport implements RunnerTransport {
     private readonly connectTimeoutMs;
     private readonly insecure;
     private readonly port;
+    private readonly pinAddresses;
+    private readonly dial;
     private readonly pools;
     constructor(options?: Http3TransportOptions);
     prewarm(regionHostname: string, sessionsPerAddress?: number): void;
@@ -9654,23 +9785,67 @@ declare class Http3Transport implements RunnerTransport {
     close(): Promise<void>;
     private poolFor;
     private buildPool;
+    /**
+     * 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.
+     */
+    private resolveAddresses;
+    /** Opens `sessionsPerAddress` connections against one address, in parallel. */
+    private openGroup;
+    /** Closes a connection slot once it connects, ignoring one that never did. */
+    private closeSlot;
+    /**
+     * 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.
+     */
+    private noteAddressFailure;
+    /**
+     * 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.
+     */
+    private rebuildPool;
     private connectSession;
     private sendRequest;
 }
 
 /**
- * Picks the best transport available, and - when HTTP/3 is available -
- * runs it against HTTP/2 per region host so a blocked or slow QUIC
- * handshake never costs a request time (RUNNER-CONTRACTS-2026-10-02.md,
- * C6; see http3-transport.ts's doc comment for the full requirement).
- *
- * Today, on a platform with no native HTTP/3 addon, this is unconditional
- * HTTP/2 with zero QUIC probing - see http3-transport.ts.
+ * Picks the transport for a region host.
+ *
+ * HTTP/2 unless the caller opts into racing HTTP/3 against it. A platform
+ * with no native HTTP/3 addon is always HTTP/2 with zero QUIC probing
+ * either way - see http3-transport.ts.
+ *
+ * Why HTTP/2 is the default rather than the race: on a cold burst the race
+ * costs several times what HTTP/2 does. The promotion to HTTP/3 is decided
+ * by address 0's *connection* being ready, while every request for that host
+ * is then spread over all of its sessions, so a burst is dispatched onto
+ * HTTP/3 sessions that have not carried a request yet. Measured on one region
+ * host at c=100, alternating order, three runs each: TTI p50 203 / 221 / 267 ms
+ * on the race against 51 / 53 / 50 ms on HTTP/2 at 4 sessions per address, and
+ * 28 / 55 / 235 / 250 ms against 43 / 57 / 52 / 66 ms at the default 8. Once the
+ * pool is genuinely warm HTTP/3 is the faster of the two, so it stays available
+ * for callers who can pre-warm it; it is just not a safe default for the first
+ * burst, and a first burst is what a latency benchmark measures.
  */
 
 interface BestTransportOptions {
     http2?: Http2TransportOptions;
     http3?: Http3TransportOptions;
+    /**
+     * Race HTTP/3 against HTTP/2 per region host. Default false, for the reason
+     * in this module's doc comment. HTTP/3 still only ever promotes a host for
+     * *future* requests, so opting in never delays a request in flight.
+     */
+    raceHttp3?: boolean | undefined;
 }
 interface BestTransportResult {
     transport: RunnerTransport;
@@ -9766,6 +9941,14 @@ declare class RunnerError extends Error {
      * two carries it.
      */
     get isBusy(): boolean;
+    /**
+     * `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(): boolean;
     /** C2: the runner doesn't serve this create shape at all - send it to api.miosa.ai instead. */
     get isUnsupportedRequest(): boolean;
 }