Introduce an API to establish channels (#16)

* Introduce an API to establish channels

* Rename expectChannel to expectTunnel

I think I'm using the word 'channel' for the individual streams within a
connection, and the word 'tunnel' for the overall bundle of streams that
are going over a given TCP socket.

* Rename ChannelTunnel to KubernetesTunnel

* Streams don't need 'close', they have a writable.

* Let's add tunnel protocols to types I guess

Author: danopia

lib/contract.ts

@@ -21,11 +21,39 @@ export interface RequestOptions {
   bodyStream?: ReadableStream<Uint8Array>;
 
   accept?: string;
+  expectTunnel?: string[];
   expectStream?: boolean;
   expectJson?: boolean;
 }
 
+export interface KubernetesTunnel<Tproto extends string> {
+  /** Indicates which network protocol is in use.
+   * This changes semantics, largely due to Kubernetes tunnel API quirks. */
+  readonly transportProtocol: 'SPDY' | 'WebSocket' | 'Opaque';
+  readonly subProtocol: Tproto;
+  /** Set up a channel, using either SPDY or Websocket semantics. */
+  getChannel<
+    Treadable extends boolean,
+    Twritable extends boolean,
+  >(opts: {
+    // Different transports identify streams different ways
+    spdyHeaders?: Record<string,string | number>;
+    streamIndex?: number;
+    // What streams should be hooked up
+    readable: Treadable;
+    writable: Twritable;
+  }): Promise<{
+    readable: Treadable extends true ? ReadableStream<Uint8Array> : null;
+    writable: Twritable extends true ? WritableStream<Uint8Array> : null;
+  }>;
+  /** Call once after creating the initial channels. */
+  ready(): Promise<void>;
+  /** Disconnects the underlying transport. */
+  stop(): Promise<void>;
+}
+
 export interface RestClient {
+  performRequest<Tproto extends string>(opts: RequestOptions & {expectTunnel: Tproto[]}): Promise<KubernetesTunnel<Tproto>>;
   performRequest(opts: RequestOptions & {expectStream: true; expectJson: true}): Promise<ReadableStream<JSONValue>>;
   performRequest(opts: RequestOptions & {expectStream: true}): Promise<ReadableStream<Uint8Array>>;
   performRequest(opts: RequestOptions & {expectJson: true}): Promise<JSONValue>;

transports/via-kubeconfig.ts

@@ -103,6 +103,9 @@ export class KubeConfigRestClient implements RestClient {
       console.error(opts.method, path);
     }
 
+    if (opts.expectTunnel) throw new Error(
+      `Channel-based APIs are not currently implemented by this client.`);
+
     const headers: Record<string, string> = {};
 
     if (!this.ctx.cluster.server) throw new Error(`No server URL found in KubeConfig`);

transports/via-kubectl-raw.ts

@@ -108,6 +108,9 @@ export class KubectlRawRestClient implements RestClient {
     const hasReqBody = opts.bodyJson !== undefined || !!opts.bodyRaw || !!opts.bodyStream;
     isVerbose && console.error(opts.method, path, hasReqBody ? '(w/ body)' : '');
 
+    if (opts.expectTunnel) throw new Error(
+      `Channel-based APIs are not currently implemented by this client.`);
+
     let rawArgs = [command, ...(hasReqBody ? ['-f', '-'] : []), "--raw", path];
 
     if (command === 'patch') {