@ikonai/sdk 1.3.9 → 1.3.11

package/client/endpoint-selector.d.ts

@@ -4,9 +4,43 @@ import { LocalConfig } from './ikon-client-config';
  * Proxy connection mode.
  * - `force-proxy`: only try proxy URLs/transports (e.g. `?ikon-proxy=true`)
  * - `force-direct`: only try direct URLs/transports (e.g. `?ikon-proxy=false`)
- * - `auto`: try both, ordered by preference, with persistent learning
+ * - `force-lb`: only try the same-origin stream tier (e.g. `?ikon-proxy=lb`)
+ * - `auto`: try all of them, ordered by preference, with persistent learning
  */
-export type ProxyMode = 'force-proxy' | 'force-direct' | 'auto';
+export type ProxyMode = 'force-proxy' | 'force-direct' | 'force-lb' | 'auto';
+/**
+ * Which connect URL a session reaches its ikon server through, most permissive network first.
+ *
+ * - `direct` — the ikon server's own host and port
+ * - `proxy` — the on-host proxy, same host on 443
+ * - `lb` — the app's own origin on 443, through the fleet proxy gateway
+ *
+ * A separate axis from {@link EntrypointType}, and it has to be: the gateway advertises no
+ * WebTransport, so `proxy` and `lb` both come back as `WebSocketProxy` and the entrypoint type
+ * cannot tell them apart. Only the connect URL that answered knows which one it was.
+ */
+export type ConnectTier = 'direct' | 'proxy' | 'lb';
+/** Most permissive first — a rung is only worth trying when the ones above it failed. */
+export declare const CONNECT_TIER_LADDER: ConnectTier[];
+/**
+ * The connect URLs to attempt, best first, given what the backend offered and what this client has
+ * learned.
+ *
+ * In `auto` mode it starts at the learned rung and walks *down* before wrapping back up: the reason
+ * a rung stopped working is almost always a network that tightened, and the rungs below it are the
+ * ones that survive that. A network that loosened is caught by the background probe instead, which
+ * costs nothing on the connect path.
+ *
+ * A learned rung the backend did not offer this session resumes at the first available rung no
+ * *shallower* than it — never above it, because the rungs above are the ones already known to fail
+ * on this network. An `lb` client meeting a backend with no stream tier falls back to the deepest
+ * rung on offer rather than starting again at the top, which is also what makes the two-rung case
+ * reduce exactly to the old behaviour.
+ *
+ * A free function rather than a method so the authenticator can order without holding a selector,
+ * and so the ordering is testable on its own.
+ */
+export declare function orderConnectTiers(availableTiers: ConnectTier[], learnedTier: ConnectTier, proxyMode: ProxyMode): ConnectTier[];
 /**
  * EndpointSelector handles ordering and selection of endpoint types.
  *
@@ -24,7 +58,7 @@ export declare class EndpointSelector {
     private readonly _proxyMode;
     private readonly _websocket;
     private readonly _webtransport;
-    private _proxyPreferred;
+    private _connectTier;
     private workingEndpointType;
     constructor(config: {
         local?: LocalConfig;
@@ -33,14 +67,29 @@ export declare class EndpointSelector {
         webtransport?: boolean;
     });
     get proxyMode(): ProxyMode;
+    /** The connect tier last known to work. */
+    get connectTier(): ConnectTier;
+    /**
+     * Whether proxied entrypoint types should outrank direct ones.
+     *
+     * True for both proxied tiers: a session that reached its server through the gateway is on a
+     * network that refused the host's own ports, so the direct entrypoints will fail there too.
+     */
     get proxyPreferred(): boolean;
     /** The endpoint type last known to work, or null when nothing has been learned yet. */
     get rememberedType(): EntrypointType | null;
     /**
-     * Mark proxy as preferred and persist to localStorage.
-     * Called by IkonClient when auth-level proxy fallback succeeds in auto mode.
+     * The connect URL that just answered. Authoritative — it is the only thing that can distinguish
+     * the two proxied tiers.
      */
-    markProxyPreferred(): void;
+    recordWorkingConnectTier(tier: ConnectTier): void;
+    /**
+     * A background probe reached a tier above the one in use. Adopt it for the next connection; the
+     * current one is left alone.
+     */
+    recordReachableConnectTier(tier: ConnectTier): void;
+    /** The tiers worth probing from the one in use, best first. Empty when already at the top. */
+    getFasterConnectTiers(activeTier: ConnectTier): ConnectTier[];
     /**
      * Clear the proxy preference so the next connection tries direct first.
      */
@@ -74,6 +123,11 @@ export declare class EndpointSelector {
      * A probe reached a tier faster than the remembered one — the network is no longer the one the
      * preference was learned on. Drop the preference so the next connection starts from base
      * priority; the current connection is left alone.
+     *
+     * Only a *direct* type says anything about the connect tier. A faster proxied type (WebTransport
+     * over the proxy, say) is still reached through a proxied connect URL, so throwing an `lb` client
+     * back to the top of the ladder on that evidence would cost it the full walk to end up where it
+     * already was.
      */
     recordFasterTypeReachable(type: EntrypointType): void;
     /**
@@ -84,5 +138,10 @@ export declare class EndpointSelector {
     private filterByTransport;
     private revalidationAgeMs;
     private loadRememberedType;
-    private loadProxyPreference;
+    /**
+     * Reads nothing back into storage, deliberately: a page that loads and never connects must not
+     * create state it did not earn.
+     */
+    private loadConnectTier;
+    private setConnectTier;
 }

package/client/ikon-client-config.d.ts

@@ -360,11 +360,12 @@ export interface IkonClientConfig {
      */
     webtransport?: boolean;
     /**
-     * Force proxy or direct connection. When true, only proxy endpoint types are used.
-     * When false, proxy types are excluded.
+     * Pin the connect tier. When true, only the on-host proxy on 443 is used, and only proxy endpoint
+     * types with it. When false, proxy types are excluded. `'lb'` pins the same-origin stream tier
+     * through the fleet proxy gateway, which auto mode reaches only after the other two fail.
      * Can be overridden by the `?ikon-proxy=` query parameter.
      */
-    proxy?: boolean;
+    proxy?: boolean | 'lb';
     /**
      * Turn same-origin links into in-place route changes instead of document loads.
      *

package/client/ikon-client.d.ts

@@ -443,6 +443,18 @@ export declare class IkonClient {
      * Authenticate with the server.
      */
     private authenticate;
+    /**
+     * Walk back up the ladder in the background after landing on anything but the top rung.
+     *
+     * Only in auto mode: the probe exists to retire a learned preference, and a force mode has none to
+     * retire — it was told which tier to use. Running it anyway spends a request on the direct high
+     * port that `force-proxy` exists to avoid, and lets a reachable direct server clear a preference
+     * `EndpointSelector` promises force modes never touch.
+     *
+     * Nothing ever probes *up to* `lb`, since it is the bottom rung — so the stream tier's `/health`
+     * having no load-balancer route of its own does not matter here.
+     */
+    private probeFasterConnectTiers;
     /**
      * Handle incoming protocol message from channel manager.
      */

package/connection/authenticator.d.ts

@@ -1,12 +1,16 @@
 import { AuthResponse, ClientEnvironment } from '../../shared/protocol/src/index.ts';
 import { ApiKeyConfig, LocalConfig, SessionTokenConfig } from '../client/ikon-client-config';
-import { ProxyMode } from '../client/endpoint-selector';
+import { ConnectTier, ProxyMode } from '../client/endpoint-selector';
 /**
  * Result of authentication - contains the AuthResponse from the server.
  */
 export interface AuthResult {
     authResponse: AuthResponse;
     usedProxyUrl?: boolean;
+    /** Which connect-URL rung answered. */
+    connectTier?: ConnectTier;
+    /** Every rung offered this session, absolute, so the client can probe the ones above the winner. */
+    connectTierUrls?: Partial<Record<ConnectTier, string>>;
     directUrl?: string;
     backendUrl?: string;
     authToken?: string;
@@ -43,7 +47,7 @@ export declare function authenticateLocal(config: LocalConfig, signal?: AbortSig
  * 2. POST /init to create profile, resolve the app session, and wait for running
  * 3. Connect to the returned Ikon server URL
  */
-export declare function authenticateApiKey(config: ApiKeyConfig, signal?: AbortSignal, proxyMode?: ProxyMode, proxyPreferred?: boolean): Promise<AuthResult>;
+export declare function authenticateApiKey(config: ApiKeyConfig, signal?: AbortSignal, proxyMode?: ProxyMode, learnedTier?: ConnectTier): Promise<AuthResult>;
 /**
  * Authenticate with the Ikon backend using a pre-obtained session token.
  * Use this when the token was obtained from auth.ikonai.com (OAuth) or /auth/anonymous.
@@ -53,4 +57,4 @@ export declare function authenticateApiKey(config: ApiKeyConfig, signal?: AbortS
  * 2. POST /init to create profile, resolve the app session, and wait for running
  * 3. Connect to the returned Ikon server URL
  */
-export declare function authenticateSessionToken(config: SessionTokenConfig, signal?: AbortSignal, proxyMode?: ProxyMode, proxyPreferred?: boolean): Promise<AuthResult>;
+export declare function authenticateSessionToken(config: SessionTokenConfig, signal?: AbortSignal, proxyMode?: ProxyMode, learnedTier?: ConnectTier): Promise<AuthResult>;

package/connection/urls.d.ts

@@ -20,6 +20,16 @@ export declare const IKON_AUTH_BASE_URL = "https://auth.ikonai.com";
  * cloud / non-browser. Requires the app LB to route `/ikon/auth/* → auth backend`.
  */
 export declare function getSameOriginAuthUrl(): string | null;
+/**
+ * Resolve the stream tier's connect path (`/ikon/stream/connect?…`) against the page origin.
+ *
+ * The backend hands this one over as a path rather than a URL because it cannot know the origin: an
+ * app may be served from a customer domain that appears nowhere in the Space document. That origin
+ * is the whole point of the tier — it is the one hostname a network that allowlists this app must
+ * already pass. Returns null off cloud / non-browser. Requires the app LB to route
+ * `/ikon/stream/* → proxy gateway`.
+ */
+export declare function getSameOriginStreamUrl(streamPath: string): string | null;
 /**
  * Get backend URL from BackendType.
  * Defaults to same-origin /ikon/api on deployed apps; honors ?ikon-api=false to opt out.

package/index.d.ts

@@ -5,7 +5,7 @@ export type { ConnectionState } from './client/connection-state';
 export { isConnecting, isConnected, isOffline, isError } from './client/connection-state';
 export { ChannelManager, type ChannelManagerConfig, type ChannelManagerState } from './channel/channel-manager';
 export { Channel, type ChannelConfig, type ChannelState } from './channel/channel';
-export { EndpointSelector, type ProxyMode } from './client/endpoint-selector';
+export { EndpointSelector, orderConnectTiers, CONNECT_TIER_LADDER, type ConnectTier, type ProxyMode } from './client/endpoint-selector';
 export { ConnectionError, AuthenticationError, TransportError, KeepaliveTimeoutError, AuthRejectedError, MaxRetriesExceededError, ProvisioningTimeoutError, AppStartupFailedError, SpaceNotFoundError, AccessDeniedError, ServerFullError, SessionNotFoundError, ServerUnavailableError, BrowserNotSupportedError } from './errors';
 export { checkBrowserSupport, type BrowserSupportResult } from './utils/browser-support';
 export { Opcode, EntrypointType, UserType, ClientType, ContextType } from '../shared/protocol/src/index.ts';
@@ -20,7 +20,7 @@ export { abortSignalTimeout, abortSignalAny } from './utils/abort-signal';
 export { createPkceChallenge, takePkceVerifier, restorePkceVerifier, isPkceSupported } from './utils/pkce';
 export { isEmbedded, startEmbeddedOAuthSignIn, adoptPkceVerifierFromUrl, onEmbeddedOAuthResult, PKCE_URL_PARAM, type EmbeddedOAuthResult } from './utils/embedded-oauth';
 export { initializeInspectMode, isInspectModeEnabled, enableInspectMode, IKON_INSPECT_MODE_CHANGED_EVENT } from './utils/inspect-mode';
-export { getLangParam, getProxyParam, getWebSocketParam, getWebTransportParam, getDebugParam, getServerUrlParam, getConnectParam, getAudioParam, getVideoParam, getWebRtcParam, getInspectParam, getDebugOverlayParam, getAuthSameOriginParam, getRetryParam, setSdkUrlParam, IKON_PARAM_PROXY, IKON_PARAM_WEBSOCKET, IKON_PARAM_WEBTRANSPORT, IKON_PARAM_DEBUG, IKON_PARAM_LANG, IKON_PARAM_SERVER_URL, IKON_PARAM_CONNECT, IKON_PARAM_AUDIO, IKON_PARAM_VIDEO, IKON_PARAM_WEBRTC, IKON_PARAM_INSPECT, IKON_PARAM_DEBUG_OVERLAY, IKON_PARAM_AUTH, IKON_PARAM_RETRY } from './utils/query-params';
+export { getLangParam, getProxyParam, getProxyTierParam, getWebSocketParam, getWebTransportParam, getDebugParam, getServerUrlParam, getConnectParam, getAudioParam, getVideoParam, getWebRtcParam, getInspectParam, getDebugOverlayParam, getAuthSameOriginParam, getRetryParam, setSdkUrlParam, IKON_PARAM_PROXY, IKON_PARAM_WEBSOCKET, IKON_PARAM_WEBTRANSPORT, IKON_PARAM_DEBUG, IKON_PARAM_LANG, IKON_PARAM_SERVER_URL, IKON_PARAM_CONNECT, IKON_PARAM_AUDIO, IKON_PARAM_VIDEO, IKON_PARAM_WEBRTC, IKON_PARAM_INSPECT, IKON_PARAM_DEBUG_OVERLAY, IKON_PARAM_AUTH, IKON_PARAM_RETRY } from './utils/query-params';
 export { getOpcodeName } from './utils/opcode-names';
 export { initializeLogSink, setSendLogsCallback, getBufferedLogs, takeBufferedLogs, flushLogs, clearLogBuffer, getLogBufferSize } from './utils/log-sink';
 export type { LogSinkConfig } from './utils/log-sink';