diff --git a/src/plugins/discover/public/url_generator.ts b/src/plugins/discover/public/url_generator.ts index 21bdbf225d6aa5..63dea20fecc0a1 100644 --- a/src/plugins/discover/public/url_generator.ts +++ b/src/plugins/discover/public/url_generator.ts @@ -6,16 +6,10 @@ * Side Public License, v 1. */ -import { - TimeRange, - Filter, - Query, - esFilters, - QueryState, - RefreshInterval, -} from '../../data/public'; +import type { UrlGeneratorsDefinition } from '../../share/public'; +import type { TimeRange, Filter, Query, QueryState, RefreshInterval } from '../../data/public'; +import { esFilters } from '../../data/public'; import { setStateToKbnUrl } from '../../kibana_utils/public'; -import { UrlGeneratorsDefinition } from '../../share/public'; export const DISCOVER_APP_URL_GENERATOR = 'DISCOVER_APP_URL_GENERATOR'; @@ -71,10 +65,12 @@ export interface DiscoverUrlGeneratorState { * Used interval of the histogram */ interval?: string; + /** * Array of the used sorting [[field,direction],...] */ sort?: string[][]; + /** * id of the used saved query */ diff --git a/src/plugins/share/common/url_service/__tests__/locators.test.ts b/src/plugins/share/common/url_service/__tests__/locators.test.ts new file mode 100644 index 00000000000000..45d727df7de48c --- /dev/null +++ b/src/plugins/share/common/url_service/__tests__/locators.test.ts @@ -0,0 +1,165 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import { of } from 'src/plugins/kibana_utils/common'; +import { testLocator, TestLocatorState, urlServiceTestSetup } from './setup'; + +describe('locators', () => { + test('can start locators service', () => { + const { + service: { locators }, + } = urlServiceTestSetup(); + + expect(typeof locators).toBe('object'); + expect(typeof locators.create).toBe('function'); + expect(typeof locators.get).toBe('function'); + }); + + test('returns "undefined" for unregistered locator', () => { + const { + service: { locators }, + } = urlServiceTestSetup(); + + expect(locators.get(testLocator.id)).toBe(undefined); + }); + + test('can register a locator', () => { + const { + service: { locators }, + } = urlServiceTestSetup(); + + locators.create(testLocator); + expect(typeof locators.get(testLocator.id)).toBe('object'); + }); + + test('getLocation() returns KibanaLocation generated by the locator', async () => { + const { + service: { locators }, + } = urlServiceTestSetup(); + + locators.create(testLocator); + + const locator = locators.get(testLocator.id); + const location = await locator?.getLocation({ + savedObjectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', + pageNumber: 21, + showFlyout: true, + }); + + expect(location).toEqual({ + app: 'test_app', + route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=21', + state: { isFlyoutOpen: true }, + }); + }); + + describe('.navigate()', () => { + test('throws if navigation method is not implemented', async () => { + const { + service: { locators }, + } = urlServiceTestSetup(); + const locator = locators.create(testLocator); + const [, error] = await of( + locator.navigate({ + pageNumber: 1, + savedObjectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', + showFlyout: false, + }) + ); + + expect(error).toBeInstanceOf(Error); + expect(error.message).toBe('not implemented'); + }); + + test('navigates user when .navigate() method is called', async () => { + const { + service: { locators }, + deps, + } = urlServiceTestSetup({ + navigate: jest.fn(async () => {}), + }); + const locator = locators.create(testLocator); + const [, error] = await of( + locator.navigate({ + pageNumber: 1, + savedObjectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', + showFlyout: false, + }) + ); + + expect(error).toBe(undefined); + expect(deps.navigate).toHaveBeenCalledTimes(1); + expect(deps.navigate).toHaveBeenCalledWith( + { + app: 'test_app', + route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=1', + state: { + isFlyoutOpen: false, + }, + }, + { replace: false } + ); + }); + + test('can specify "replace" navigation parameter', async () => { + const { + service: { locators }, + deps, + } = urlServiceTestSetup({ + navigate: jest.fn(async () => {}), + }); + const locator = locators.create(testLocator); + + await locator.navigate( + { + pageNumber: 1, + savedObjectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', + showFlyout: false, + }, + { + replace: false, + } + ); + + expect(deps.navigate).toHaveBeenCalledTimes(1); + expect(deps.navigate).toHaveBeenCalledWith( + { + app: 'test_app', + route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=1', + state: { + isFlyoutOpen: false, + }, + }, + { replace: false } + ); + + await locator.navigate( + { + pageNumber: 2, + savedObjectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', + showFlyout: false, + }, + { + replace: true, + } + ); + + expect(deps.navigate).toHaveBeenCalledTimes(2); + expect(deps.navigate).toHaveBeenCalledWith( + { + app: 'test_app', + route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=2', + state: { + isFlyoutOpen: false, + }, + }, + { replace: true } + ); + }); + }); +}); diff --git a/src/plugins/share/common/url_service/__tests__/setup.ts b/src/plugins/share/common/url_service/__tests__/setup.ts new file mode 100644 index 00000000000000..ad13bb8d8d2160 --- /dev/null +++ b/src/plugins/share/common/url_service/__tests__/setup.ts @@ -0,0 +1,42 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import type { SerializableState } from 'src/plugins/kibana_utils/common'; +import { LocatorDefinition } from '../locators'; +import { UrlService, UrlServiceDependencies } from '../url_service'; + +export interface TestLocatorState extends SerializableState { + savedObjectId: string; + showFlyout: boolean; + pageNumber: number; +} + +export const testLocator: LocatorDefinition = { + id: 'TEST_LOCATOR', + getLocation: async ({ savedObjectId, pageNumber, showFlyout }) => { + return { + app: 'test_app', + route: `/my-object/${savedObjectId}?page=${pageNumber}`, + state: { + isFlyoutOpen: showFlyout, + }, + }; + }, +}; + +export const urlServiceTestSetup = (partialDeps: Partial = {}) => { + const deps: UrlServiceDependencies = { + navigate: async () => { + throw new Error('not implemented'); + }, + ...partialDeps, + }; + const service = new UrlService(deps); + + return { service, deps }; +}; diff --git a/src/plugins/share/common/url_service/index.ts b/src/plugins/share/common/url_service/index.ts new file mode 100644 index 00000000000000..84f74356bcf186 --- /dev/null +++ b/src/plugins/share/common/url_service/index.ts @@ -0,0 +1,10 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +export * from './url_service'; +export * from './locators'; diff --git a/src/plugins/share/common/url_service/locators/index.ts b/src/plugins/share/common/url_service/locators/index.ts new file mode 100644 index 00000000000000..f9f87215eb4db5 --- /dev/null +++ b/src/plugins/share/common/url_service/locators/index.ts @@ -0,0 +1,11 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +export * from './types'; +export * from './locator'; +export * from './locator_client'; diff --git a/src/plugins/share/common/url_service/locators/locator.ts b/src/plugins/share/common/url_service/locators/locator.ts new file mode 100644 index 00000000000000..68c3b05a7f4111 --- /dev/null +++ b/src/plugins/share/common/url_service/locators/locator.ts @@ -0,0 +1,69 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import type { SavedObjectReference } from 'kibana/server'; +import type { PersistableState, SerializableState } from 'src/plugins/kibana_utils/common'; +import type { + LocatorDefinition, + LocatorPublic, + KibanaLocation, + LocatorNavigationParams, +} from './types'; + +export interface LocatorDependencies { + navigate: (location: KibanaLocation, params?: LocatorNavigationParams) => Promise; +} + +export class Locator

implements PersistableState

, LocatorPublic

{ + public readonly migrations: PersistableState

['migrations']; + + constructor( + public readonly definition: LocatorDefinition

, + protected readonly deps: LocatorDependencies + ) { + this.migrations = definition.migrations || {}; + } + + // PersistableState

------------------------------------------------------- + + public readonly telemetry: PersistableState

['telemetry'] = ( + state: P, + stats: Record + ): Record => { + return this.definition.telemetry ? this.definition.telemetry(state, stats) : stats; + }; + + public readonly inject: PersistableState

['inject'] = ( + state: P, + references: SavedObjectReference[] + ): P => { + return this.definition.inject ? this.definition.inject(state, references) : state; + }; + + public readonly extract: PersistableState

['extract'] = ( + state: P + ): { state: P; references: SavedObjectReference[] } => { + return this.definition.extract ? this.definition.extract(state) : { state, references: [] }; + }; + + // LocatorPublic

---------------------------------------------------------- + + public async getLocation(params: P): Promise { + return await this.definition.getLocation(params); + } + + public async navigate( + params: P, + { replace = false }: LocatorNavigationParams = {} + ): Promise { + const location = await this.getLocation(params); + await this.deps.navigate(location, { + replace, + }); + } +} diff --git a/src/plugins/share/common/url_service/locators/locator_client.ts b/src/plugins/share/common/url_service/locators/locator_client.ts new file mode 100644 index 00000000000000..168cc02d03ff15 --- /dev/null +++ b/src/plugins/share/common/url_service/locators/locator_client.ts @@ -0,0 +1,47 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import type { SerializableState } from 'src/plugins/kibana_utils/common'; +import type { LocatorDependencies } from './locator'; +import type { LocatorDefinition, LocatorPublic, ILocatorClient } from './types'; +import { Locator } from './locator'; + +export type LocatorClientDependencies = LocatorDependencies; + +export class LocatorClient implements ILocatorClient { + /** + * Collection of registered locators. + */ + protected locators: Map> = new Map(); + + constructor(protected readonly deps: LocatorClientDependencies) {} + + /** + * Creates and register a URL locator. + * + * @param definition A definition of URL locator. + * @returns A public interface of URL locator. + */ + public create

(definition: LocatorDefinition

): LocatorPublic

{ + const locator = new Locator

(definition, this.deps); + + this.locators.set(definition.id, locator); + + return locator; + } + + /** + * Returns a previously registered URL locator. + * + * @param id ID of a URL locator. + * @returns A public interface of a registered URL locator. + */ + public get

(id: string): undefined | LocatorPublic

{ + return this.locators.get(id); + } +} diff --git a/src/plugins/share/common/url_service/locators/types.ts b/src/plugins/share/common/url_service/locators/types.ts new file mode 100644 index 00000000000000..d811ae0fd4aa23 --- /dev/null +++ b/src/plugins/share/common/url_service/locators/types.ts @@ -0,0 +1,91 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import { PersistableState, SerializableState } from 'src/plugins/kibana_utils/common'; + +/** + * URL locator registry. + */ +export interface ILocatorClient { + /** + * Create and register a new locator. + * + * @param urlGenerator Definition of the new locator. + */ + create

(locatorDefinition: LocatorDefinition

): LocatorPublic

; + + /** + * Retrieve a previously registered locator. + * + * @param id Unique ID of the locator. + */ + get

(id: string): undefined | LocatorPublic

; +} + +/** + * A convenience interface used to define and register a locator. + */ +export interface LocatorDefinition

+ extends Partial> { + /** + * Unique ID of the locator. Should be constant and unique across Kibana. + */ + id: string; + + /** + * Returns a deep link, including location state, which can be used for + * navigation in Kibana. + * + * @param params Parameters from which to generate a Kibana location. + */ + getLocation(params: P): Promise; +} + +/** + * Public interface of a registered locator. + */ +export interface LocatorPublic

{ + /** + * Returns a relative URL to the client-side redirect endpoint using this + * locator. (This method is necessary for compatibility with URL generators.) + */ + getLocation(params: P): Promise; + + /** + * Navigate using the `core.application.navigateToApp()` method to a Kibana + * location generated by this locator. This method is available only on the + * browser. + */ + navigate(params: P, navigationParams?: LocatorNavigationParams): Promise; +} + +export interface LocatorNavigationParams { + replace?: boolean; +} + +/** + * This interface represents a location in Kibana to which one can navigate + * using the `core.application.navigateToApp()` method. + */ +export interface KibanaLocation { + /** + * Kibana application ID. + */ + app: string; + + /** + * A URL route within a Kibana application. + */ + route: string; + + /** + * A serializable location state object, which the app can use to determine + * what should be displayed on the screen. + */ + state: S; +} diff --git a/src/plugins/share/common/url_service/url_service.ts b/src/plugins/share/common/url_service/url_service.ts new file mode 100644 index 00000000000000..0c3a0aabb750bc --- /dev/null +++ b/src/plugins/share/common/url_service/url_service.ts @@ -0,0 +1,23 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import { LocatorClient, LocatorClientDependencies } from './locators'; + +export type UrlServiceDependencies = LocatorClientDependencies; + +/** + * Common URL Service client interface for server-side and client-side. + */ +export class UrlService { + /** + * Client to work with locators. + */ + locators: LocatorClient = new LocatorClient(this.deps); + + constructor(protected readonly deps: UrlServiceDependencies) {} +} diff --git a/src/plugins/share/public/plugin.ts b/src/plugins/share/public/plugin.ts index 14d74e055cbd9a..eb7c46cdaef867 100644 --- a/src/plugins/share/public/plugin.ts +++ b/src/plugins/share/public/plugin.ts @@ -18,6 +18,7 @@ import { UrlGeneratorsSetup, UrlGeneratorsStart, } from './url_generators/url_generator_service'; +import { UrlService } from '../common/url_service'; export interface ShareSetupDependencies { securityOss?: SecurityOssPluginSetup; @@ -27,16 +28,60 @@ export interface ShareStartDependencies { securityOss?: SecurityOssPluginStart; } +/** @public */ +export type SharePluginSetup = ShareMenuRegistrySetup & { + /** + * @deprecated + * + * URL Generators are deprecated use UrlService instead. + */ + urlGenerators: UrlGeneratorsSetup; + + /** + * Utilities to work with URL locators and short URLs. + */ + url: UrlService; +}; + +/** @public */ +export type SharePluginStart = ShareMenuManagerStart & { + /** + * @deprecated + * + * URL Generators are deprecated use UrlService instead. + */ + urlGenerators: UrlGeneratorsStart; + + /** + * Utilities to work with URL locators and short URLs. + */ + url: UrlService; +}; + export class SharePlugin implements Plugin { private readonly shareMenuRegistry = new ShareMenuRegistry(); private readonly shareContextMenu = new ShareMenuManager(); private readonly urlGeneratorsService = new UrlGeneratorsService(); + private url?: UrlService; public setup(core: CoreSetup, plugins: ShareSetupDependencies): SharePluginSetup { core.application.register(createShortUrlRedirectApp(core, window.location)); + + this.url = new UrlService({ + navigate: async (location, { replace = false } = {}) => { + const [start] = await core.getStartServices(); + await start.application.navigateToApp(location.app, { + path: location.route, + state: location.state, + replace, + }); + }, + }); + return { ...this.shareMenuRegistry.setup(), urlGenerators: this.urlGeneratorsService.setup(core), + url: this.url, }; } @@ -48,16 +93,7 @@ export class SharePlugin implements Plugin { plugins.securityOss?.anonymousAccess ), urlGenerators: this.urlGeneratorsService.start(core), + url: this.url!, }; } } - -/** @public */ -export type SharePluginSetup = ShareMenuRegistrySetup & { - urlGenerators: UrlGeneratorsSetup; -}; - -/** @public */ -export type SharePluginStart = ShareMenuManagerStart & { - urlGenerators: UrlGeneratorsStart; -}; diff --git a/src/plugins/share/public/url_generators/README.md b/src/plugins/share/public/url_generators/README.md index 39ee5f2901e916..f948354aad9593 100644 --- a/src/plugins/share/public/url_generators/README.md +++ b/src/plugins/share/public/url_generators/README.md @@ -1,3 +1,9 @@ +# URL Generators are deprecated + +__Below is documentation of URL Generators, which are now deprecated and will be removed in favor of URL locators in 7.14.__ + +--- + ## URL Generator Services Developers who maintain pages in Kibana that other developers may want to link to diff --git a/src/plugins/share/public/url_generators/url_generator_service.ts b/src/plugins/share/public/url_generators/url_generator_service.ts index 982f0692102df6..5a8e7a1b5c17a8 100644 --- a/src/plugins/share/public/url_generators/url_generator_service.ts +++ b/src/plugins/share/public/url_generators/url_generator_service.ts @@ -13,10 +13,20 @@ import { UrlGeneratorInternal } from './url_generator_internal'; import { UrlGeneratorContract } from './url_generator_contract'; export interface UrlGeneratorsStart { + /** + * @deprecated + * + * URL Generators are deprecated, use URL locators in UrlService instead. + */ getUrlGenerator: (urlGeneratorId: T) => UrlGeneratorContract; } export interface UrlGeneratorsSetup { + /** + * @deprecated + * + * URL Generators are deprecated, use URL locators in UrlService instead. + */ registerUrlGenerator: ( generator: UrlGeneratorsDefinition ) => UrlGeneratorContract; diff --git a/src/plugins/share/server/plugin.ts b/src/plugins/share/server/plugin.ts index 744a4148215c3e..6e3c68935f77bf 100644 --- a/src/plugins/share/server/plugin.ts +++ b/src/plugins/share/server/plugin.ts @@ -12,11 +12,30 @@ import { CoreSetup, Plugin, PluginInitializerContext } from 'kibana/server'; import { createRoutes } from './routes/create_routes'; import { url } from './saved_objects'; import { CSV_SEPARATOR_SETTING, CSV_QUOTE_VALUES_SETTING } from '../common/constants'; +import { UrlService } from '../common/url_service'; + +/** @public */ +export interface SharePluginSetup { + url: UrlService; +} + +/** @public */ +export interface SharePluginStart { + url: UrlService; +} + +export class SharePlugin implements Plugin { + private url?: UrlService; -export class SharePlugin implements Plugin { constructor(private readonly initializerContext: PluginInitializerContext) {} public setup(core: CoreSetup) { + this.url = new UrlService({ + navigate: async () => { + throw new Error('Locator .navigate() does not work on server.'); + }, + }); + createRoutes(core, this.initializerContext.logger.get()); core.savedObjects.registerType(url); core.uiSettings.register({ @@ -41,10 +60,18 @@ export class SharePlugin implements Plugin { schema: schema.boolean(), }, }); + + return { + url: this.url, + }; } public start() { this.initializerContext.logger.get().debug('Starting plugin'); + + return { + url: this.url!, + }; } public stop() {