wip update apis

packages/services/src/kernel/default.ts

@@ -21,6 +21,10 @@ import {
   ISignal, Signal
 } from '@phosphor/signaling';
 
+import {
+  ServerConnection
+} from '../utils';
+
 import {
   CommHandler
 } from './comm';
@@ -43,13 +47,6 @@ import * as serialize
 import * as validate
   from './validate';
 
-import {
-  IAjaxSettings
-} from '../utils';
-
-import * as utils
-  from '../utils';
-
 
 /**
  * The url for the kernel service.
@@ -73,12 +70,7 @@ class DefaultKernel implements Kernel.IKernel {
   constructor(options: Kernel.IOptions, id: string) {
     this._name = options.name;
     this._id = id;
-    this._baseUrl = options.baseUrl || PageConfig.getBaseUrl();
-    this._wsUrl = options.wsUrl || PageConfig.getWsUrl(this._baseUrl);
-    this._ajaxSettings = JSON.stringify(
-      utils.ajaxSettingsWithToken(options.ajaxSettings, options.token)
-    );
-    this._token = options.token || PageConfig.getOption('token');
+    this.serverSettings = options.serverSettings || ServerConnection.makeSettings();
     this._clientId = options.clientId || uuid();
     this._username = options.username || '';
     this._futures = new Map<string, KernelFutureHandler>();
@@ -94,6 +86,11 @@ class DefaultKernel implements Kernel.IKernel {
    */
   readonly terminated: Signal<this, void>;
 
+  /**
+   * The server settings for the kernel.
+   */
+  readonly serverSettings: ServerConnection.ISettings;
+
   /**
    * A signal emitted when the kernel status changes.
    */
@@ -157,26 +154,6 @@ class DefaultKernel implements Kernel.IKernel {
     return this._status;
   }
 
-  /**
-   * The base url of the kernel.
-   */
-  get baseUrl(): string {
-    return this._baseUrl;
-  }
-
-  /**
-   * Get a copy of the default ajax settings for the kernel.
-   */
-  get ajaxSettings(): IAjaxSettings {
-    return JSON.parse(this._ajaxSettings);
-  }
-  /**
-   * Set the default ajax settings for the kernel.
-   */
-  set ajaxSettings(value: IAjaxSettings) {
-    this._ajaxSettings = JSON.stringify(value);
-  }
-
   /**
    * Test whether the kernel has been disposed.
    */
@@ -217,11 +194,7 @@ class DefaultKernel implements Kernel.IKernel {
     if (this._specPromise) {
       return this._specPromise;
     }
-    let options = {
-      baseUrl: this._baseUrl,
-      ajaxSettings: this.ajaxSettings
-    };
-    this._specPromise = Private.findSpecs(options).then(specs => {
+    this._specPromise = Private.findSpecs(this.serverSettings).then(specs => {
       return specs.kernelspecs[this._name];
     });
     return this._specPromise;
@@ -232,12 +205,9 @@ class DefaultKernel implements Kernel.IKernel {
    */
   clone(): Kernel.IKernel {
     let options: Kernel.IOptions = {
-      baseUrl: this._baseUrl,
-      wsUrl: this._wsUrl,
       name: this._name,
       username: this._username,
-      token: this._token,
-      ajaxSettings: this.ajaxSettings
+      serverSettings: this.serverSettings
     };
     return new DefaultKernel(options, this._id);
   }
@@ -383,7 +353,7 @@ class DefaultKernel implements Kernel.IKernel {
     this._clearState();
     return this.ready.then(() => {
       return Private.shutdownKernel(
-        this.id, this._baseUrl, this.ajaxSettings
+        this.id, this.serverSettings
       );
     });
   }
@@ -649,7 +619,8 @@ class DefaultKernel implements Kernel.IKernel {
    * Create the kernel websocket connection and add socket status handlers.
    */
   private _createSocket(): void {
-    let partialUrl = URLExt.join(this._wsUrl, KERNEL_SERVICE_URL,
+    let settings = this.serverSettings;
+    let partialUrl = URLExt.join(settings.wsUrl, KERNEL_SERVICE_URL,
                                  encodeURIComponent(this._id));
     // Strip any authentication from the display string.
     let parsed = URLExt.parse(partialUrl);

packages/services/src/kernel/kernel.ts

@@ -18,8 +18,8 @@ import {
 } from '@phosphor/signaling';
 
 import {
-  IAjaxSettings
-} from '../utils';
+  ServerConnection
+} from '..';
 
 import {
   DefaultKernel
@@ -373,14 +373,9 @@ namespace Kernel {
     unhandledMessage: ISignal<this, KernelMessage.IMessage>;
 
     /**
-     * The base url of the kernel.
+     * The server settings for the kernel.
      */
-    readonly baseUrl: string;
-
-    /**
-     * The Ajax settings used for server requests.
-     */
-    ajaxSettings: IAjaxSettings;
+    readonly serverSettings: ServerConnection.ISettings;
 
     /**
      * Shutdown a kernel.
@@ -405,47 +400,65 @@ namespace Kernel {
   /**
    * Find a kernel by id.
    *
+   * @param id - The id of the kernel of interest.
+   *
+   * @param settings - The optional server settings.
+   *
+   * @returns A promise that resolves with the model for the kernel.
+   *
    * #### Notes
    * If the kernel was already started via `startNewKernel`, we return its
    * `Kernel.IModel`.
    *
-   * Otherwise, if `options` are given, we attempt to find to the existing
+   * Otherwise, we attempt to find to the existing
    * kernel.
    * The promise is fulfilled when the kernel is found,
    * otherwise the promise is rejected.
    */
   export
-  function findById(id: string, options?: IOptions): Promise<IModel> {
-    return DefaultKernel.findById(id, options);
+  function findById(id: string, settings?: ServerConnection.ISettings): Promise<IModel> {
+    return DefaultKernel.findById(id, settings);
   }
 
   /**
    * Fetch all of the kernel specs.
    *
+   * @param settings - The optional server settings.
+   *
+   * @returns A promise that resolves with the kernel specs.
+   *
    * #### Notes
    * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernelspecs).
    */
   export
-  function getSpecs(options: Kernel.IOptions = {}): Promise<Kernel.ISpecModels> {
-    return DefaultKernel.getSpecs(options);
+  function getSpecs(settings?: ServerConnection.ISettings): Promise<Kernel.ISpecModels> {
+    return DefaultKernel.getSpecs(settings);
   }
 
   /**
    * Fetch the running kernels.
    *
+   * @param settings - The optional server settings.
+   *
+   * @returns A promise that resolves with the list of running kernels.
+   *
    * #### Notes
    * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
    *
    * The promise is fulfilled on a valid response and rejected otherwise.
    */
   export
-  function listRunning(options: Kernel.IOptions = {}): Promise<Kernel.IModel[]> {
+  function listRunning(settings?: ServerConnection.ISettings): Promise<ReadonlyArray<Kernel.IModel>> {
     return DefaultKernel.listRunning(options);
   }
 
   /**
    * Start a new kernel.
    *
+   * @param options - The options used to create the kernel.
+   *
+   * @returns A promise that resolves with a kernel object.
+   *
    * #### Notes
    * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
    *
@@ -464,6 +477,12 @@ namespace Kernel {
   /**
    * Connect to a running kernel.
    *
+   * @param id - The id of the running kernel.
+   *
+   * @param settings - The server settings for the request.
+   *
+   * @returns A promise that resolves with the kernel object.
+   *
    * #### Notes
    * If the kernel was already started via `startNewKernel`, the existing
    * Kernel object info is used to create another instance.
@@ -477,20 +496,24 @@ namespace Kernel {
    * the promise is rejected.
    */
   export
-  function connectTo(id: string, options?: Kernel.IOptions): Promise<IKernel> {
+  function connectTo(id: string, settings?: ServerConnection.ISettings): Promise<IKernel> {
     return DefaultKernel.connectTo(id, options);
   }
 
   /**
    * Shut down a kernel by id.
+   *
+   * @param id - The id of the running kernel.
+   *
+   * @param settings - The server settings for the request.
+   *
+   * @returns A promise that resolves when the kernel is shut down.
    */
   export
-  function shutdown(id: string, options: Kernel.IOptions = {}): Promise<void> {
-    return DefaultKernel.shutdown(id, options);
+  function shutdown(id: string, settings?: ServerConnection.ISettings): Promise<void> {
+    return DefaultKernel.shutdown(id, settings);
   }
 
-  /**
-   * The interface of a kernel
   /**
    * The options object used to initialize a kernel.
    */
@@ -502,15 +525,9 @@ namespace Kernel {
     name?: string;
 
     /**
-     * The root url of the kernel server.
-     * Default is location.origin in browsers, notebook-server default otherwise.
+     * The server settings for the kernel.
      */
-    baseUrl?: string;
-
-    /**
-     * The url to access websockets, if different from baseUrl.
-     */
-    wsUrl?: string;
+    serverSettings?: ServerConnection.ISettings;
 
     /**
      * The username of the kernel client.
@@ -521,16 +538,6 @@ namespace Kernel {
      * The unique identifier for the kernel client.
      */
     clientId?: string;
-
-    /**
-     * The authentication token for the API.
-     */
-    token?: string;
-
-    /**
-     * The default ajax settings to use for the kernel.
-     */
-    ajaxSettings?: IAjaxSettings;
   }
 
   /**
@@ -553,19 +560,9 @@ namespace Kernel {
     runningChanged: ISignal<IManager, IModel[]>;
 
     /**
-     * The base url of the manager.
+     * The server settings for the manager.
      */
-    readonly baseUrl: string;
-
-    /**
-     * The base ws url of the manager.
-     */
-    readonly wsUrl: string;
-
-    /**
-     * The default ajax settings for the manager.
-     */
-    ajaxSettings?: IAjaxSettings;
+    serverSettings?: ServerConnection.ISettings;
 
     /**
      * The kernel spec models.
@@ -622,9 +619,7 @@ namespace Kernel {
      * @returns A promise that resolves with the kernel instance.
      *
      * #### Notes
-     * If options are given, the baseUrl and wsUrl will be forced
-     * to the ones used by the manager.  The ajaxSettings of the manager
-     * will be used unless overridden.
+     * The manager `serverSettings` will be always be used.
      */
     startNew(options?: IOptions): Promise<IKernel>;
 
@@ -642,16 +637,12 @@ namespace Kernel {
      *
      * @param id - The id of the target kernel.
      *
-     * @param options - The kernel options to use.
-     *
      * @returns A promise that resolves with the new kernel instance.
      *
      * #### Notes
-     * If options are given, the baseUrl and wsUrl will be forced
-     * to the ones used by the manager. The ajaxSettings of the manager
-     * will be used unless overridden.
+     * The manager `serverSettings` will be always be used.
      */
-    connectTo(id: string, options?: IOptions): Promise<IKernel>;
+    connectTo(id: string): Promise<IKernel>;
 
     /**
      * Shut down a kernel by id.

packages/services/src/terminal/terminal.ts

@@ -251,8 +251,7 @@ namespace TerminalSession {
      * @returns A promise that resolves with the terminal instance.
      *
      * #### Notes
-     * The manager `serverSettings` will be used unless overridden in the
-     * options.
+     * The manager `serverSettings` will be always be used.
      */
     startNew(options?: IOptions): Promise<ISession>;
 
@@ -261,15 +260,9 @@ namespace TerminalSession {
      *
      * @param name - The name of the target session.
      *
-     * @param options - The options used to connect to the session.
-     *
      * @returns A promise that resolves with the new session instance.
-     *
-     * #### Notes
-     * The manager `serverSettings` will be used unless overridden in the
-     * options.
      */
-    connectTo(name: string, options?: IOptions): Promise<ISession>;
+    connectTo(name: string): Promise<ISession>;
 
     /**
      * Shut down a terminal session by name.