[7.x] [data.search] Server-side background session service (#81099)

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchoptions.isrestore.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISearchOptions](./kibana-plugin-plugins-data-public.isearchoptions.md) &gt; [isRestore](./kibana-plugin-plugins-data-public.isearchoptions.isrestore.md)
+
+## ISearchOptions.isRestore property
+
+Whether the session is restored (i.e. search requests should re-use the stored search IDs, rather than starting from scratch)
+
+<b>Signature:</b>
+
+```typescript
+isRestore?: boolean;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchoptions.isstored.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISearchOptions](./kibana-plugin-plugins-data-public.isearchoptions.md) &gt; [isStored](./kibana-plugin-plugins-data-public.isearchoptions.isstored.md)
+
+## ISearchOptions.isStored property
+
+Whether the session is already saved (i.e. sent to background)
+
+<b>Signature:</b>
+
+```typescript
+isStored?: boolean;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isearchoptions.md

@@ -15,6 +15,8 @@ export interface ISearchOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [abortSignal](./kibana-plugin-plugins-data-public.isearchoptions.abortsignal.md) | <code>AbortSignal</code> | An <code>AbortSignal</code> that allows the caller of <code>search</code> to abort a search request. |
+|  [isRestore](./kibana-plugin-plugins-data-public.isearchoptions.isrestore.md) | <code>boolean</code> | Whether the session is restored (i.e. search requests should re-use the stored search IDs, rather than starting from scratch) |
+|  [isStored](./kibana-plugin-plugins-data-public.isearchoptions.isstored.md) | <code>boolean</code> | Whether the session is already saved (i.e. sent to background) |
 |  [sessionId](./kibana-plugin-plugins-data-public.isearchoptions.sessionid.md) | <code>string</code> | A session ID, grouping multiple search requests into a single session. |
 |  [strategy](./kibana-plugin-plugins-data-public.isearchoptions.strategy.md) | <code>string</code> | Use this option to force using a specific server side search strategy. Leave empty to use the default strategy. |
 

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.delete.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISessionService](./kibana-plugin-plugins-data-public.isessionservice.md) &gt; [delete](./kibana-plugin-plugins-data-public.isessionservice.delete.md)
+
+## ISessionService.delete property
+
+Deletes a session
+
+<b>Signature:</b>
+
+```typescript
+delete: (sessionId: string) => Promise<void>;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.find.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISessionService](./kibana-plugin-plugins-data-public.isessionservice.md) &gt; [find](./kibana-plugin-plugins-data-public.isessionservice.find.md)
+
+## ISessionService.find property
+
+Gets a list of saved sessions
+
+<b>Signature:</b>
+
+```typescript
+find: (options: SearchSessionFindOptions) => Promise<SavedObjectsFindResponse<BackgroundSessionSavedObjectAttributes>>;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.get.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISessionService](./kibana-plugin-plugins-data-public.isessionservice.md) &gt; [get](./kibana-plugin-plugins-data-public.isessionservice.get.md)
+
+## ISessionService.get property
+
+Gets a saved session
+
+<b>Signature:</b>
+
+```typescript
+get: (sessionId: string) => Promise<SavedObject<BackgroundSessionSavedObjectAttributes>>;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.isrestore.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISessionService](./kibana-plugin-plugins-data-public.isessionservice.md) &gt; [isRestore](./kibana-plugin-plugins-data-public.isessionservice.isrestore.md)
+
+## ISessionService.isRestore property
+
+Whether the active session is restored (i.e. reusing previous search IDs)
+
+<b>Signature:</b>
+
+```typescript
+isRestore: () => boolean;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.isstored.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISessionService](./kibana-plugin-plugins-data-public.isessionservice.md) &gt; [isStored](./kibana-plugin-plugins-data-public.isessionservice.isstored.md)
+
+## ISessionService.isStored property
+
+Whether the active session is already saved (i.e. sent to background)
+
+<b>Signature:</b>
+
+```typescript
+isStored: () => boolean;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.md

@@ -15,8 +15,15 @@ export interface ISessionService
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [clear](./kibana-plugin-plugins-data-public.isessionservice.clear.md) | <code>() =&gt; void</code> | Clears the active session. |
+|  [delete](./kibana-plugin-plugins-data-public.isessionservice.delete.md) | <code>(sessionId: string) =&gt; Promise&lt;void&gt;</code> | Deletes a session |
+|  [find](./kibana-plugin-plugins-data-public.isessionservice.find.md) | <code>(options: SearchSessionFindOptions) =&gt; Promise&lt;SavedObjectsFindResponse&lt;BackgroundSessionSavedObjectAttributes&gt;&gt;</code> | Gets a list of saved sessions |
+|  [get](./kibana-plugin-plugins-data-public.isessionservice.get.md) | <code>(sessionId: string) =&gt; Promise&lt;SavedObject&lt;BackgroundSessionSavedObjectAttributes&gt;&gt;</code> | Gets a saved session |
 |  [getSession$](./kibana-plugin-plugins-data-public.isessionservice.getsession_.md) | <code>() =&gt; Observable&lt;string &#124; undefined&gt;</code> | Returns the observable that emits an update every time the session ID changes |
 |  [getSessionId](./kibana-plugin-plugins-data-public.isessionservice.getsessionid.md) | <code>() =&gt; string &#124; undefined</code> | Returns the active session ID |
-|  [restore](./kibana-plugin-plugins-data-public.isessionservice.restore.md) | <code>(sessionId: string) =&gt; void</code> | Restores existing session |
+|  [isRestore](./kibana-plugin-plugins-data-public.isessionservice.isrestore.md) | <code>() =&gt; boolean</code> | Whether the active session is restored (i.e. reusing previous search IDs) |
+|  [isStored](./kibana-plugin-plugins-data-public.isessionservice.isstored.md) | <code>() =&gt; boolean</code> | Whether the active session is already saved (i.e. sent to background) |
+|  [restore](./kibana-plugin-plugins-data-public.isessionservice.restore.md) | <code>(sessionId: string) =&gt; Promise&lt;SavedObject&lt;BackgroundSessionSavedObjectAttributes&gt;&gt;</code> | Restores existing session |
+|  [save](./kibana-plugin-plugins-data-public.isessionservice.save.md) | <code>(name: string, url: string) =&gt; Promise&lt;SavedObject&lt;BackgroundSessionSavedObjectAttributes&gt;&gt;</code> | Saves a session |
 |  [start](./kibana-plugin-plugins-data-public.isessionservice.start.md) | <code>() =&gt; string</code> | Starts a new session |
+|  [update](./kibana-plugin-plugins-data-public.isessionservice.update.md) | <code>(sessionId: string, attributes: Partial&lt;BackgroundSessionSavedObjectAttributes&gt;) =&gt; Promise&lt;any&gt;</code> | Updates a session |
 

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.restore.md

@@ -9,5 +9,5 @@ Restores existing session
 <b>Signature:</b>
 
 ```typescript
-restore: (sessionId: string) => void;
+restore: (sessionId: string) => Promise<SavedObject<BackgroundSessionSavedObjectAttributes>>;
 ```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.save.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISessionService](./kibana-plugin-plugins-data-public.isessionservice.md) &gt; [save](./kibana-plugin-plugins-data-public.isessionservice.save.md)
+
+## ISessionService.save property
+
+Saves a session
+
+<b>Signature:</b>
+
+```typescript
+save: (name: string, url: string) => Promise<SavedObject<BackgroundSessionSavedObjectAttributes>>;
+```

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.isessionservice.update.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [ISessionService](./kibana-plugin-plugins-data-public.isessionservice.md) &gt; [update](./kibana-plugin-plugins-data-public.isessionservice.update.md)
+
+## ISessionService.update property
+
+Updates a session
+
+<b>Signature:</b>
+
+```typescript
+update: (sessionId: string, attributes: Partial<BackgroundSessionSavedObjectAttributes>) => Promise<any>;
+```

docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.isrestore.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) &gt; [ISearchOptions](./kibana-plugin-plugins-data-server.isearchoptions.md) &gt; [isRestore](./kibana-plugin-plugins-data-server.isearchoptions.isrestore.md)
+
+## ISearchOptions.isRestore property
+
+Whether the session is restored (i.e. search requests should re-use the stored search IDs, rather than starting from scratch)
+
+<b>Signature:</b>
+
+```typescript
+isRestore?: boolean;
+```

docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.isstored.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-server](./kibana-plugin-plugins-data-server.md) &gt; [ISearchOptions](./kibana-plugin-plugins-data-server.isearchoptions.md) &gt; [isStored](./kibana-plugin-plugins-data-server.isearchoptions.isstored.md)
+
+## ISearchOptions.isStored property
+
+Whether the session is already saved (i.e. sent to background)
+
+<b>Signature:</b>
+
+```typescript
+isStored?: boolean;
+```

docs/development/plugins/data/server/kibana-plugin-plugins-data-server.isearchoptions.md

@@ -15,6 +15,8 @@ export interface ISearchOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [abortSignal](./kibana-plugin-plugins-data-server.isearchoptions.abortsignal.md) | <code>AbortSignal</code> | An <code>AbortSignal</code> that allows the caller of <code>search</code> to abort a search request. |
+|  [isRestore](./kibana-plugin-plugins-data-server.isearchoptions.isrestore.md) | <code>boolean</code> | Whether the session is restored (i.e. search requests should re-use the stored search IDs, rather than starting from scratch) |
+|  [isStored](./kibana-plugin-plugins-data-server.isearchoptions.isstored.md) | <code>boolean</code> | Whether the session is already saved (i.e. sent to background) |
 |  [sessionId](./kibana-plugin-plugins-data-server.isearchoptions.sessionid.md) | <code>string</code> | A session ID, grouping multiple search requests into a single session. |
 |  [strategy](./kibana-plugin-plugins-data-server.isearchoptions.strategy.md) | <code>string</code> | Use this option to force using a specific server side search strategy. Leave empty to use the default strategy. |
 

examples/search_examples/kibana.json

@@ -4,7 +4,7 @@
   "kibanaVersion": "kibana",
   "server": true,
   "ui": true,
-  "requiredPlugins": ["navigation", "data", "developerExamples"],
+  "requiredPlugins": ["navigation", "data", "developerExamples", "kibanaUtils"],
   "optionalPlugins": [],
   "requiredBundles": []
 }

src/plugins/data/common/search/session/index.ts

@@ -17,4 +17,5 @@
  * under the License.
  */
 
+export * from './status';
 export * from './types';

src/plugins/data/common/search/session/mocks.ts

@@ -27,5 +27,12 @@ export function getSessionServiceMock(): jest.Mocked<ISessionService> {
     restore: jest.fn(),
     getSessionId: jest.fn(),
     getSession$: jest.fn(() => new BehaviorSubject(undefined).asObservable()),
+    isStored: jest.fn(),
+    isRestore: jest.fn(),
+    save: jest.fn(),
+    get: jest.fn(),
+    find: jest.fn(),
+    update: jest.fn(),
+    delete: jest.fn(),
   };
 }

src/plugins/data/common/search/session/status.ts

@@ -0,0 +1,26 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export enum BackgroundSessionStatus {
+  IN_PROGRESS = 'in_progress',
+  ERROR = 'error',
+  COMPLETE = 'complete',
+  CANCELLED = 'cancelled',
+  EXPIRED = 'expired',
+}

src/plugins/data/common/search/session/types.ts

@@ -18,6 +18,7 @@
  */
 
 import { Observable } from 'rxjs';
+import type { SavedObject, SavedObjectsFindResponse } from 'kibana/server';
 
 export interface ISessionService {
   /**
@@ -30,6 +31,17 @@ export interface ISessionService {
    * @returns `Observable`
    */
   getSession$: () => Observable<string | undefined>;
+
+  /**
+   * Whether the active session is already saved (i.e. sent to background)
+   */
+  isStored: () => boolean;
+
+  /**
+   * Whether the active session is restored (i.e. reusing previous search IDs)
+   */
+  isRestore: () => boolean;
+
   /**
    * Starts a new session
    */
@@ -38,10 +50,58 @@ export interface ISessionService {
   /**
    * Restores existing session
    */
-  restore: (sessionId: string) => void;
+  restore: (sessionId: string) => Promise<SavedObject<BackgroundSessionSavedObjectAttributes>>;
 
   /**
    * Clears the active session.
    */
   clear: () => void;
+
+  /**
+   * Saves a session
+   */
+  save: (name: string, url: string) => Promise<SavedObject<BackgroundSessionSavedObjectAttributes>>;
+
+  /**
+   * Gets a saved session
+   */
+  get: (sessionId: string) => Promise<SavedObject<BackgroundSessionSavedObjectAttributes>>;
+
+  /**
+   * Gets a list of saved sessions
+   */
+  find: (
+    options: SearchSessionFindOptions
+  ) => Promise<SavedObjectsFindResponse<BackgroundSessionSavedObjectAttributes>>;
+
+  /**
+   * Updates a session
+   */
+  update: (
+    sessionId: string,
+    attributes: Partial<BackgroundSessionSavedObjectAttributes>
+  ) => Promise<any>;
+
+  /**
+   * Deletes a session
+   */
+  delete: (sessionId: string) => Promise<void>;
+}
+
+export interface BackgroundSessionSavedObjectAttributes {
+  name: string;
+  created: string;
+  expires: string;
+  status: string;
+  initialState: Record<string, unknown>;
+  restoreState: Record<string, unknown>;
+  idMapping: Record<string, string>;
+}
+
+export interface SearchSessionFindOptions {
+  page?: number;
+  perPage?: number;
+  sortField?: string;
+  sortOrder?: string;
+  filter?: string;
 }

src/plugins/data/common/search/types.ts

@@ -92,4 +92,15 @@ export interface ISearchOptions {
    * A session ID, grouping multiple search requests into a single session.
    */
   sessionId?: string;
+
+  /**
+   * Whether the session is already saved (i.e. sent to background)
+   */
+  isStored?: boolean;
+
+  /**
+   * Whether the session is restored (i.e. search requests should re-use the stored search IDs,
+   * rather than starting from scratch)
+   */
+  isRestore?: boolean;
 }

src/plugins/data/common/utils/index.ts

@@ -19,3 +19,4 @@
 
 /** @internal */
 export { shortenDottedString } from './shorten_dotted_string';
+export { tapFirst } from './tap_first';

src/plugins/data/common/utils/tap_first.test.ts

@@ -0,0 +1,30 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { of } from 'rxjs';
+import { tapFirst } from './tap_first';
+
+describe('tapFirst', () => {
+  it('should tap the first and only the first', () => {
+    const fn = jest.fn();
+    of(1, 2, 3).pipe(tapFirst(fn)).subscribe();
+    expect(fn).toBeCalledTimes(1);
+    expect(fn).lastCalledWith(1);
+  });
+});