1 | import { IIterator } from '@lumino/algorithm';
|
2 | import { IDisposable, IObservableDisposable } from '@lumino/disposable';
|
3 | import { ISignal } from '@lumino/signaling';
|
4 | import { Kernel, KernelMessage } from '../kernel';
|
5 | import { ServerConnection } from '..';
|
6 | import { IChangedArgs } from '@jupyterlab/coreutils';
|
7 | /**
|
8 | * Interface of a session object.
|
9 | *
|
10 | * A session object represents a live connection to a session kernel.
|
11 | *
|
12 | * This represents a persistent kernel connection with a particular key,
|
13 | * that persists across changing kernels and kernels getting terminated. As
|
14 | * such, a number of signals are proxied from the current kernel for
|
15 | * convenience.
|
16 | *
|
17 | * The kernel is owned by the session, in that the session creates the
|
18 | * kernel and manages its lifecycle.
|
19 | */
|
20 | export interface ISessionConnection extends IObservableDisposable {
|
21 | /**
|
22 | * A signal emitted when a session property changes.
|
23 | */
|
24 | readonly propertyChanged: ISignal<this, 'path' | 'name' | 'type'>;
|
25 | /**
|
26 | * A signal emitted when the kernel changes.
|
27 | */
|
28 | kernelChanged: ISignal<this, IChangedArgs<Kernel.IKernelConnection | null, Kernel.IKernelConnection | null, 'kernel'>>;
|
29 | /**
|
30 | * The kernel statusChanged signal, proxied from the current kernel.
|
31 | */
|
32 | statusChanged: ISignal<this, Kernel.Status>;
|
33 | /**
|
34 | * The kernel connectionStatusChanged signal, proxied from the current
|
35 | * kernel.
|
36 | */
|
37 | connectionStatusChanged: ISignal<this, Kernel.ConnectionStatus>;
|
38 | /**
|
39 | * The kernel pendingInput signal, proxied from the current
|
40 | * kernel.
|
41 | */
|
42 | pendingInput: ISignal<this, boolean>;
|
43 | /**
|
44 | * The kernel iopubMessage signal, proxied from the current kernel.
|
45 | */
|
46 | iopubMessage: ISignal<this, KernelMessage.IIOPubMessage>;
|
47 | /**
|
48 | * The kernel unhandledMessage signal, proxied from the current kernel.
|
49 | */
|
50 | unhandledMessage: ISignal<this, KernelMessage.IMessage>;
|
51 | /**
|
52 | * The kernel anyMessage signal, proxied from the current kernel.
|
53 | */
|
54 | anyMessage: ISignal<this, Kernel.IAnyMessageArgs>;
|
55 | /**
|
56 | * Unique id of the session.
|
57 | */
|
58 | readonly id: string;
|
59 | /**
|
60 | * The current path associated with the session.
|
61 | */
|
62 | readonly path: string;
|
63 | /**
|
64 | * The current name associated with the session.
|
65 | */
|
66 | readonly name: string;
|
67 | /**
|
68 | * The type of the session.
|
69 | */
|
70 | readonly type: string;
|
71 | /**
|
72 | * The server settings of the session.
|
73 | */
|
74 | readonly serverSettings: ServerConnection.ISettings;
|
75 | /**
|
76 | * The model associated with the session.
|
77 | */
|
78 | readonly model: IModel;
|
79 | /**
|
80 | * The kernel.
|
81 | *
|
82 | * #### Notes
|
83 | * This is a read-only property, and can be altered by [changeKernel].
|
84 | *
|
85 | * A number of kernel signals are proxied through the session from
|
86 | * whatever the current kernel is for convenience.
|
87 | */
|
88 | readonly kernel: Kernel.IKernelConnection | null;
|
89 | /**
|
90 | * Change the session path.
|
91 | *
|
92 | * @param path - The new session path.
|
93 | *
|
94 | * @returns A promise that resolves when the session has renamed.
|
95 | *
|
96 | * #### Notes
|
97 | * This uses the Jupyter REST API, and the response is validated.
|
98 | * The promise is fulfilled on a valid response and rejected otherwise.
|
99 | */
|
100 | setPath(path: string): Promise<void>;
|
101 | /**
|
102 | * Change the session name.
|
103 | *
|
104 | * @returns A promise that resolves when the session has renamed.
|
105 | *
|
106 | * #### Notes
|
107 | * This uses the Jupyter REST API, and the response is validated.
|
108 | * The promise is fulfilled on a valid response and rejected otherwise.
|
109 | */
|
110 | setName(name: string): Promise<void>;
|
111 | /**
|
112 | * Change the session type.
|
113 | *
|
114 | * @returns A promise that resolves when the session has renamed.
|
115 | *
|
116 | * #### Notes
|
117 | * This uses the Jupyter REST API, and the response is validated.
|
118 | * The promise is fulfilled on a valid response and rejected otherwise.
|
119 | */
|
120 | setType(type: string): Promise<void>;
|
121 | /**
|
122 | * Change the kernel.
|
123 | *
|
124 | * @param options - The name or id of the new kernel.
|
125 | *
|
126 | * @returns A promise that resolves with the new kernel model.
|
127 | *
|
128 | * #### Notes
|
129 | * This shuts down the existing kernel and creates a new kernel, keeping
|
130 | * the existing session ID and path. The session assumes it owns the
|
131 | * kernel.
|
132 | *
|
133 | * To start now kernel, pass an empty dictionary.
|
134 | */
|
135 | changeKernel(options: Partial<Kernel.IModel>): Promise<Kernel.IKernelConnection | null>;
|
136 | /**
|
137 | * Kill the kernel and shutdown the session.
|
138 | *
|
139 | * @returns A promise that resolves when the session is shut down.
|
140 | *
|
141 | * #### Notes
|
142 | * This uses the Jupyter REST API, and the response is validated.
|
143 | * The promise is fulfilled on a valid response and rejected otherwise.
|
144 | */
|
145 | shutdown(): Promise<void>;
|
146 | }
|
147 | export declare namespace ISessionConnection {
|
148 | /**
|
149 | * The session initialization options.
|
150 | */
|
151 | interface IOptions {
|
152 | /**
|
153 | * Session model.
|
154 | */
|
155 | model: IModel;
|
156 | /**
|
157 | * Connects to an existing kernel
|
158 | */
|
159 | connectToKernel(options: Kernel.IKernelConnection.IOptions): Kernel.IKernelConnection;
|
160 | /**
|
161 | * The server settings.
|
162 | */
|
163 | serverSettings?: ServerConnection.ISettings;
|
164 | /**
|
165 | * The username of the session client.
|
166 | */
|
167 | username?: string;
|
168 | /**
|
169 | * The unique identifier for the session client.
|
170 | */
|
171 | clientId?: string;
|
172 | /**
|
173 | * Kernel connection options
|
174 | */
|
175 | kernelConnectionOptions?: Omit<Kernel.IKernelConnection.IOptions, 'model' | 'username' | 'clientId' | 'serverSettings'>;
|
176 | }
|
177 | /**
|
178 | * An arguments object for the kernel changed signal.
|
179 | */
|
180 | type IKernelChangedArgs = IChangedArgs<Kernel.IKernelConnection | null, Kernel.IKernelConnection | null, 'kernel'>;
|
181 | }
|
182 | /**
|
183 | * Object which manages session instances.
|
184 | *
|
185 | * #### Notes
|
186 | * The manager is responsible for maintaining the state of running
|
187 | * sessions.
|
188 | */
|
189 | export interface IManager extends IDisposable {
|
190 | /**
|
191 | * A signal emitted when the running sessions change.
|
192 | */
|
193 | runningChanged: ISignal<this, IModel[]>;
|
194 | /**
|
195 | * A signal emitted when there is a connection failure.
|
196 | */
|
197 | connectionFailure: ISignal<IManager, ServerConnection.NetworkError>;
|
198 | /**
|
199 | * The server settings for the manager.
|
200 | */
|
201 | serverSettings?: ServerConnection.ISettings;
|
202 | /**
|
203 | * Test whether the manager is ready.
|
204 | */
|
205 | readonly isReady: boolean;
|
206 | /**
|
207 | * A promise that is fulfilled when the manager is ready.
|
208 | */
|
209 | readonly ready: Promise<void>;
|
210 | /**
|
211 | * Create an iterator over the known running sessions.
|
212 | *
|
213 | * @returns A new iterator over the running sessions.
|
214 | */
|
215 | running(): IIterator<IModel>;
|
216 | /**
|
217 | * Start a new session.
|
218 | *
|
219 | * @param createOptions - Options for creating the session
|
220 | *
|
221 | * @param connectOptions - Options for connecting to the session
|
222 | *
|
223 | * @returns A promise that resolves with a session connection instance.
|
224 | *
|
225 | * #### Notes
|
226 | * The `serverSettings` and `connectToKernel` options of the manager will be used.
|
227 | */
|
228 | startNew(createOptions: ISessionOptions, connectOptions?: Omit<ISessionConnection.IOptions, 'model' | 'connectToKernel' | 'serverSettings'>): Promise<ISessionConnection>;
|
229 | /**
|
230 | * Find a session by id.
|
231 | *
|
232 | * @param id - The id of the target session.
|
233 | *
|
234 | * @returns A promise that resolves with the session's model.
|
235 | */
|
236 | findById(id: string): Promise<IModel | undefined>;
|
237 | /**
|
238 | * Find a session by path.
|
239 | *
|
240 | * @param path - The path of the target session.
|
241 | *
|
242 | * @returns A promise that resolves with the session's model.
|
243 | */
|
244 | findByPath(path: string): Promise<IModel | undefined>;
|
245 | /**
|
246 | * Connect to a running session.
|
247 | *
|
248 | * @param model - The model of the target session.
|
249 | *
|
250 | * @param options - The session options to use.
|
251 | *
|
252 | * @returns The new session instance.
|
253 | */
|
254 | connectTo(options: Omit<ISessionConnection.IOptions, 'connectToKernel' | 'serverSettings'>): ISessionConnection;
|
255 | /**
|
256 | * Shut down a session by id.
|
257 | *
|
258 | * @param id - The id of the target kernel.
|
259 | *
|
260 | * @returns A promise that resolves when the operation is complete.
|
261 | */
|
262 | shutdown(id: string): Promise<void>;
|
263 | /**
|
264 | * Shut down all sessions.
|
265 | *
|
266 | * @returns A promise that resolves when all of the sessions are shut down.
|
267 | */
|
268 | shutdownAll(): Promise<void>;
|
269 | /**
|
270 | * Force a refresh of the running sessions.
|
271 | *
|
272 | * @returns A promise that resolves when the models are refreshed.
|
273 | *
|
274 | * #### Notes
|
275 | * This is intended to be called only in response to a user action,
|
276 | * since the manager maintains its internal state.
|
277 | */
|
278 | refreshRunning(): Promise<void>;
|
279 | /**
|
280 | * Find a session associated with a path and stop it is the only session
|
281 | * using that kernel.
|
282 | *
|
283 | * @param path - The path in question.
|
284 | *
|
285 | * @returns A promise that resolves when the relevant sessions are stopped.
|
286 | */
|
287 | stopIfNeeded(path: string): Promise<void>;
|
288 | }
|
289 | /**
|
290 | * The session model returned by the server.
|
291 | *
|
292 | * #### Notes
|
293 | * See the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/sessions).
|
294 | */
|
295 | export interface IModel {
|
296 | /**
|
297 | * The unique identifier for the session client.
|
298 | */
|
299 | readonly id: string;
|
300 | readonly name: string;
|
301 | readonly path: string;
|
302 | readonly type: string;
|
303 | readonly kernel: Kernel.IModel | null;
|
304 | }
|
305 | /**
|
306 | * A session request.
|
307 | *
|
308 | * #### Notes
|
309 | * The `path` and `type` session model parameters are required. The `name`
|
310 | * parameter is not technically required, but is often assumed to be nonempty,
|
311 | * so we require it too.
|
312 | *
|
313 | * See the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/sessions).
|
314 | */
|
315 | export declare type ISessionOptions = Pick<IModel, 'path' | 'type' | 'name'> & {
|
316 | kernel?: Partial<Pick<Kernel.IModel, 'name'>>;
|
317 | };
|