feat: add browser routing cache

examples/browser-routing.ts

@@ -0,0 +1,19 @@
+import Kernel from '@onkernel/sdk';
+
+async function main() {
+  const kernel = new Kernel({
+    browserRouting: {
+      enabled: true,
+      subresources: ['computer'],
+    },
+  });
+
+  const browser = await kernel.browsers.create({});
+  await kernel.browsers.computer.clickMouse(browser.session_id, { x: 10, y: 10 });
+  const response = await kernel.browsers.fetch(browser.session_id, 'https://example.com', { method: 'GET' });
+  console.log('status', response.status);
+
+  await kernel.browsers.deleteByID(browser.session_id);
+}
+
+void main();

package.json

@@ -45,6 +45,7 @@
     "prettier": "^3.0.0",
     "publint": "^0.2.12",
     "ts-jest": "^29.1.0",
+    "ts-morph": "^28.0.0",
     "ts-node": "^10.5.0",
     "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.9/tsc-multi.tgz",
     "tsconfig-paths": "^4.0.0",

src/client.ts

@@ -20,6 +20,11 @@
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import { AppListParams, AppListResponse, AppListResponsesOffsetPagination, Apps } from './resources/apps';
+import {
+  BrowserRouteCache,
+  createRoutingFetch,
+  type BrowserRoutingOptions,
+} from './lib/browser-routing';
 import {
   BrowserPool,
   BrowserPoolAcquireParams,
@@ -194,6 +199,11 @@
    */
   fetch?: Fetch | undefined;
 
+  /**
+   * Configure direct-to-VM routing for browser subresource requests.
+   */
+  browserRouting?: BrowserRoutingOptions | undefined;
+
   /**
    * The maximum number of times that the client will retry a request in case of a
    * temporary failure, like a network error or a 5XX error from the server.
@@ -247,9 +257,11 @@
   fetchOptions: MergedRequestInit | undefined;
 
   private fetch: Fetch;
+  private rawFetch: Fetch;
   #encoder: Opts.RequestEncoder;
   protected idempotencyHeader?: string;
   private _options: ClientOptions;
+  public browserRouteCache: BrowserRouteCache;
 
   /**
    * API Client for interfacing with the Kernel API.
@@ -312,7 +324,16 @@
       defaultLogLevel;
     this.fetchOptions = options.fetchOptions;
     this.maxRetries = options.maxRetries ?? 2;
-    this.fetch = options.fetch ?? Shims.getDefaultFetch();
+    this.rawFetch = options.fetch ?? Shims.getDefaultFetch();
+    this.browserRouteCache = options.browserRouting?.cache ?? new BrowserRouteCache();
+    this.fetch =
+      options.browserRouting?.enabled ?
+        createRoutingFetch(this.rawFetch, {
+          apiBaseURL: this.baseURL,
+          subresources: options.browserRouting.subresources ?? [],
+          cache: this.browserRouteCache,
+        })
+      : this.rawFetch;
     this.#encoder = Opts.FallbackEncoder;
 
     this._options = options;
@@ -324,6 +345,23 @@
    * Create a new client instance re-using the same options given to the current client with optional overriding.
    */
   withOptions(options: Partial<ClientOptions>): this {
+    const currentRouting = this._options.browserRouting;
+    const nextBrowserRouting =
+      options.browserRouting === undefined ?
+        {
+          ...(currentRouting ?? {}),
+          cache: currentRouting?.cache ?? this.browserRouteCache,
+        }
+      : options.browserRouting.enabled ?
+        {
+          ...options.browserRouting,
+          cache: options.browserRouting.cache ?? this.browserRouteCache,
+        }
+      : {
+          ...options.browserRouting,
+          cache: options.browserRouting.cache ?? this.browserRouteCache,
+        };
+
     const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)({
       ...this._options,
       environment: options.environment ? options.environment : undefined,
@@ -332,10 +370,11 @@
       timeout: this.timeout,
       logger: this.logger,
       logLevel: this.logLevel,
-      fetch: this.fetch,
+      fetch: this.rawFetch,
       fetchOptions: this.fetchOptions,
       apiKey: this.apiKey,
       ...options,
+      browserRouting: nextBrowserRouting,
     });
     return client;
   }

src/index.ts

@@ -5,6 +5,12 @@ export { Kernel as default } from './client';
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
 export { Kernel, type ClientOptions } from './client';
+export {
+  BrowserRouteCache,
+  type BrowserFetchInit,
+  type BrowserRoute,
+  type BrowserRoutingOptions,
+} from './lib/browser-routing';
 export { PagePromise } from './core/pagination';
 export {
   KernelError,