@runblackcat/sdk 0.1.0-alpha.91 → 0.1.0-alpha.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runblackcat/sdk",
-  "version": "0.1.0-alpha.91",
+  "version": "0.1.0-alpha.93",
   "description": "TypeScript SDK for the Blackcat sandbox gateway",
   "license": "Apache-2.0",
   "repository": "https://github.com/TreebeardHQ/blackcat",

package/sdk/dist/index.d.ts

@@ -535,6 +535,21 @@ export interface SshKeyGrant {
     /** The sandbox's SSH host public key; pin it before connecting. */
     host_key: string;
 }
+/**
+ * Where and how to reach a port inside a sandbox through the gateway. Send
+ * `headers` with every request and with the WebSocket handshake; the gateway
+ * strips them before the application sees the request. A browser `WebSocket`
+ * cannot send headers, so the WebSocket form is for server-side clients.
+ */
+export interface PortConnection {
+    /** HTTPS URL of the path on the port. */
+    url: string;
+    /** The same target as a `wss:` URL. */
+    websocketUrl: string;
+    headers: {
+        Authorization: string;
+    };
+}
 export interface RenewSandboxResponse {
     id: string;
     expires_at: SystemTimeValue;
@@ -913,6 +928,15 @@ declare class SandboxesResource {
      * with `CONNECT /v1/sandboxes/{id}/ssh`, or let `blackcat sandbox ssh` do it.
      */
     grantSshKey(id: string, input: GrantSshKeyInput): Promise<SshKeyGrant>;
+    /**
+     * Describe a tunnel to `port` (any TCP port the sandbox listens on, not only
+     * a declared preview port), at `path` on that port. Needs the sandbox-scoped
+     * exec capability, which is checked once when a connection opens: an open
+     * WebSocket outlives it. Renews a nearly expired capability first, so call
+     * this again for each new connection. A `CONNECT` to `url` instead returns
+     * a raw byte stream, as `blackcat sandbox port-forward` uses.
+     */
+    portConnection(id: string, port: number, path?: string): Promise<PortConnection>;
     exec(id: string, input: ExecInput): Promise<ExecResult>;
     execStream(id: string, input: ExecInput): AsyncGenerator<ExecStreamChunk>;
     startProcess(id: string, requestId: string, input: ProcessStartInput): Promise<ProcessRecord>;

package/sdk/dist/index.js

@@ -482,6 +482,20 @@ class SandboxesResource {
   grantSshKey(id, input) {
     return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/ssh-keys`, input, "either");
   }
+  async portConnection(id, port, path = "/") {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+      throw new RangeError("port must be 1-65535");
+    if (!path.startsWith("/"))
+      throw new RangeError("path must start with /");
+    await this.client.renewIfNeeded();
+    const base = new URL(`v1/sandboxes/${pathSegment(id)}/ports/${port}/connect`, this.client.baseUrl);
+    const url = `${base.href}${path.startsWith("/?") || path === "/" ? path.slice(1) : path}`;
+    return {
+      url,
+      websocketUrl: url.replace(/^http/, "ws"),
+      headers: { Authorization: `Bearer ${this.client.credential("either")}` }
+    };
+  }
   async exec(id, input) {
     return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/exec`, input, "either", false, execDeadline(input)).then(execResult);
   }
@@ -721,17 +735,17 @@ class BlackcatClient extends GatewayClient {
   }
 }
 export {
-  BLACKCAT_ERROR_CODES,
-  BlackcatApiError,
-  BlackcatClient,
-  CAPABILITY_OPS,
-  MAX_EXEC_STDIN,
-  MAX_FILE_CHUNK,
-  MAX_FILE_READ_CHUNK,
-  MAX_FILE_CHUNK as MAX_FILE_WRITE_CHUNK,
-  MAX_PROCESS_STDIN,
-  assertSecureBlackcatGatewayUrl,
-  epochMillis,
+  parseSandboxBatch,
   parseCreateSandboxResponse,
-  parseSandboxBatch
+  epochMillis,
+  assertSecureBlackcatGatewayUrl,
+  MAX_PROCESS_STDIN,
+  MAX_FILE_CHUNK as MAX_FILE_WRITE_CHUNK,
+  MAX_FILE_READ_CHUNK,
+  MAX_FILE_CHUNK,
+  MAX_EXEC_STDIN,
+  CAPABILITY_OPS,
+  BlackcatClient,
+  BlackcatApiError,
+  BLACKCAT_ERROR_CODES
 };