Expressions/migrations2 (#81281)

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.executor.md

@@ -39,6 +39,8 @@ export declare class Executor<Context extends Record<string, unknown> = Record<s
 | [getType(name)](./kibana-plugin-plugins-expressions-public.executor.gettype.md) | | |
 | [getTypes()](./kibana-plugin-plugins-expressions-public.executor.gettypes.md) | | |
 | [inject(ast, references)](./kibana-plugin-plugins-expressions-public.executor.inject.md) | | |
+| [migrate(ast, version)](./kibana-plugin-plugins-expressions-public.executor.migrate.md) | | |
+| [migrateToLatest(ast, version)](./kibana-plugin-plugins-expressions-public.executor.migratetolatest.md) | | |
 | [registerFunction(functionDefinition)](./kibana-plugin-plugins-expressions-public.executor.registerfunction.md) | | |
 | [registerType(typeDefinition)](./kibana-plugin-plugins-expressions-public.executor.registertype.md) | | |
 | [run(ast, input, params)](./kibana-plugin-plugins-expressions-public.executor.run.md) | | Execute expression and return result. |

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.executor.migrate.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Executor](./kibana-plugin-plugins-expressions-public.executor.md) &gt; [migrate](./kibana-plugin-plugins-expressions-public.executor.migrate.md)
+
+## Executor.migrate() method
+
+<b>Signature:</b>
+
+```typescript
+migrate(ast: SerializableState, version: string): ExpressionAstExpression;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| ast | <code>SerializableState</code> | |
+| version | <code>string</code> | |
+
+<b>Returns:</b>
+
+`ExpressionAstExpression`
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.executor.migratetolatest.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Executor](./kibana-plugin-plugins-expressions-public.executor.md) &gt; [migrateToLatest](./kibana-plugin-plugins-expressions-public.executor.migratetolatest.md)
+
+## Executor.migrateToLatest() method
+
+<b>Signature:</b>
+
+```typescript
+migrateToLatest(ast: unknown, version: string): ExpressionAstExpression;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| ast | <code>unknown</code> | |
+| version | <code>string</code> | |
+
+<b>Returns:</b>
+
+`ExpressionAstExpression`
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionfunction.md

@@ -29,6 +29,7 @@ export declare class ExpressionFunction implements PersistableState<ExpressionAs
 | [help](./kibana-plugin-plugins-expressions-public.expressionfunction.help.md) | | <code>string</code> | A short help text. |
 | [inject](./kibana-plugin-plugins-expressions-public.expressionfunction.inject.md) | | <code>(state: ExpressionAstFunction['arguments'], references: SavedObjectReference[]) =&gt; ExpressionAstFunction['arguments']</code> | |
 | [inputTypes](./kibana-plugin-plugins-expressions-public.expressionfunction.inputtypes.md) | | <code>string[] &#124; undefined</code> | Type of inputs that this function supports. |
+| [migrations](./kibana-plugin-plugins-expressions-public.expressionfunction.migrations.md) | | <code>{</code><br/><code> [key: string]: (state: SerializableState) =&gt; SerializableState;</code><br/><code> }</code> | |
 | [name](./kibana-plugin-plugins-expressions-public.expressionfunction.name.md) | | <code>string</code> | Name of function |
 | [telemetry](./kibana-plugin-plugins-expressions-public.expressionfunction.telemetry.md) | | <code>(state: ExpressionAstFunction['arguments'], telemetryData: Record&lt;string, any&gt;) =&gt; Record&lt;string, any&gt;</code> | |
 | [type](./kibana-plugin-plugins-expressions-public.expressionfunction.type.md) | | <code>string</code> | Return type of function. This SHOULD be supplied. We use it for UI and autocomplete hinting. We may also use it for optimizations in the future. |

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionfunction.migrations.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [ExpressionFunction](./kibana-plugin-plugins-expressions-public.expressionfunction.md) &gt; [migrations](./kibana-plugin-plugins-expressions-public.expressionfunction.migrations.md)
+
+## ExpressionFunction.migrations property
+
+<b>Signature:</b>
+
+```typescript
+migrations: {
+ [key: string]: (state: SerializableState) => SerializableState;
+ };
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionsservice.md

@@ -39,6 +39,8 @@ export declare class ExpressionsService implements PersistableState<ExpressionAs
 | [getType](./kibana-plugin-plugins-expressions-public.expressionsservice.gettype.md) | | <code>ExpressionsServiceStart['getType']</code> | |
 | [getTypes](./kibana-plugin-plugins-expressions-public.expressionsservice.gettypes.md) | | <code>() =&gt; ReturnType&lt;Executor['getTypes']&gt;</code> | Returns POJO map of all registered expression types, where keys are names of the types and values are <code>ExpressionType</code> instances. |
 | [inject](./kibana-plugin-plugins-expressions-public.expressionsservice.inject.md) | | <code>(state: ExpressionAstExpression, references: SavedObjectReference[]) =&gt; ExpressionAstExpression</code> | Injects saved object references into expression AST |
+| [migrate](./kibana-plugin-plugins-expressions-public.expressionsservice.migrate.md) | | <code>(state: SerializableState, version: string) =&gt; ExpressionAstExpression</code> | Injects saved object references into expression AST |
+| [migrateToLatest](./kibana-plugin-plugins-expressions-public.expressionsservice.migratetolatest.md) | | <code>(state: unknown, version: string) =&gt; ExpressionAstExpression</code> | Injects saved object references into expression AST |
 | [registerFunction](./kibana-plugin-plugins-expressions-public.expressionsservice.registerfunction.md) | | <code>(functionDefinition: AnyExpressionFunctionDefinition &#124; (() =&gt; AnyExpressionFunctionDefinition)) =&gt; void</code> | Register an expression function, which will be possible to execute as part of the expression pipeline.<!-- -->Below we register a function which simply sleeps for given number of milliseconds to delay the execution and outputs its input as-is.
 ```ts
 expressions.registerFunction({

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionsservice.migrate.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [ExpressionsService](./kibana-plugin-plugins-expressions-public.expressionsservice.md) &gt; [migrate](./kibana-plugin-plugins-expressions-public.expressionsservice.migrate.md)
+
+## ExpressionsService.migrate property
+
+Injects saved object references into expression AST
+
+<b>Signature:</b>
+
+```typescript
+readonly migrate: (state: SerializableState, version: string) => ExpressionAstExpression;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionsservice.migratetolatest.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [ExpressionsService](./kibana-plugin-plugins-expressions-public.expressionsservice.md) &gt; [migrateToLatest](./kibana-plugin-plugins-expressions-public.expressionsservice.migratetolatest.md)
+
+## ExpressionsService.migrateToLatest property
+
+Injects saved object references into expression AST
+
+<b>Signature:</b>
+
+```typescript
+readonly migrateToLatest: (state: unknown, version: string) => ExpressionAstExpression;
+```

docs/development/plugins/expressions/server/kibana-plugin-plugins-expressions-server.executor.md

@@ -39,6 +39,8 @@ export declare class Executor<Context extends Record<string, unknown> = Record<s
 | [getType(name)](./kibana-plugin-plugins-expressions-server.executor.gettype.md) | | |
 | [getTypes()](./kibana-plugin-plugins-expressions-server.executor.gettypes.md) | | |
 | [inject(ast, references)](./kibana-plugin-plugins-expressions-server.executor.inject.md) | | |
+| [migrate(ast, version)](./kibana-plugin-plugins-expressions-server.executor.migrate.md) | | |
+| [migrateToLatest(ast, version)](./kibana-plugin-plugins-expressions-server.executor.migratetolatest.md) | | |
 | [registerFunction(functionDefinition)](./kibana-plugin-plugins-expressions-server.executor.registerfunction.md) | | |
 | [registerType(typeDefinition)](./kibana-plugin-plugins-expressions-server.executor.registertype.md) | | |
 | [run(ast, input, params)](./kibana-plugin-plugins-expressions-server.executor.run.md) | | Execute expression and return result. |

docs/development/plugins/expressions/server/kibana-plugin-plugins-expressions-server.executor.migrate.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-server](./kibana-plugin-plugins-expressions-server.md) &gt; [Executor](./kibana-plugin-plugins-expressions-server.executor.md) &gt; [migrate](./kibana-plugin-plugins-expressions-server.executor.migrate.md)
+
+## Executor.migrate() method
+
+<b>Signature:</b>
+
+```typescript
+migrate(ast: SerializableState, version: string): ExpressionAstExpression;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| ast | <code>SerializableState</code> | |
+| version | <code>string</code> | |
+
+<b>Returns:</b>
+
+`ExpressionAstExpression`
+

docs/development/plugins/expressions/server/kibana-plugin-plugins-expressions-server.executor.migratetolatest.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-server](./kibana-plugin-plugins-expressions-server.md) &gt; [Executor](./kibana-plugin-plugins-expressions-server.executor.md) &gt; [migrateToLatest](./kibana-plugin-plugins-expressions-server.executor.migratetolatest.md)
+
+## Executor.migrateToLatest() method
+
+<b>Signature:</b>
+
+```typescript
+migrateToLatest(ast: unknown, version: string): ExpressionAstExpression;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| ast | <code>unknown</code> | |
+| version | <code>string</code> | |
+
+<b>Returns:</b>
+
+`ExpressionAstExpression`
+

docs/development/plugins/expressions/server/kibana-plugin-plugins-expressions-server.expressionfunction.md

@@ -29,6 +29,7 @@ export declare class ExpressionFunction implements PersistableState<ExpressionAs
 | [help](./kibana-plugin-plugins-expressions-server.expressionfunction.help.md) | | <code>string</code> | A short help text. |
 | [inject](./kibana-plugin-plugins-expressions-server.expressionfunction.inject.md) | | <code>(state: ExpressionAstFunction['arguments'], references: SavedObjectReference[]) =&gt; ExpressionAstFunction['arguments']</code> | |
 | [inputTypes](./kibana-plugin-plugins-expressions-server.expressionfunction.inputtypes.md) | | <code>string[] &#124; undefined</code> | Type of inputs that this function supports. |
+| [migrations](./kibana-plugin-plugins-expressions-server.expressionfunction.migrations.md) | | <code>{</code><br/><code> [key: string]: (state: SerializableState) =&gt; SerializableState;</code><br/><code> }</code> | |
 | [name](./kibana-plugin-plugins-expressions-server.expressionfunction.name.md) | | <code>string</code> | Name of function |
 | [telemetry](./kibana-plugin-plugins-expressions-server.expressionfunction.telemetry.md) | | <code>(state: ExpressionAstFunction['arguments'], telemetryData: Record&lt;string, any&gt;) =&gt; Record&lt;string, any&gt;</code> | |
 | [type](./kibana-plugin-plugins-expressions-server.expressionfunction.type.md) | | <code>string</code> | Return type of function. This SHOULD be supplied. We use it for UI and autocomplete hinting. We may also use it for optimizations in the future. |

docs/development/plugins/expressions/server/kibana-plugin-plugins-expressions-server.expressionfunction.migrations.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-server](./kibana-plugin-plugins-expressions-server.md) &gt; [ExpressionFunction](./kibana-plugin-plugins-expressions-server.expressionfunction.md) &gt; [migrations](./kibana-plugin-plugins-expressions-server.expressionfunction.migrations.md)
+
+## ExpressionFunction.migrations property
+
+<b>Signature:</b>
+
+```typescript
+migrations: {
+ [key: string]: (state: SerializableState) => SerializableState;
+ };
+```

src/plugins/expressions/common/executor/executor.test.ts

@@ -22,6 +22,7 @@ import * as expressionTypes from '../expression_types';
 import * as expressionFunctions from '../expression_functions';
 import { Execution } from '../execution';
 import { ExpressionAstFunction, parseExpression } from '../ast';
+import { MigrateFunction } from '../../../kibana_utils/common/persistable_state';
 
 describe('Executor', () => {
  test('can instantiate', () => {
@@ -158,6 +159,7 @@ describe('Executor', () => {
 
  const injectFn = jest.fn().mockImplementation((args, references) => args);
  const extractFn = jest.fn().mockReturnValue({ args: {}, references: [] });
+ const migrateFn = jest.fn().mockImplementation((args) => args);
 
  const fooFn = {
  name: 'foo',
@@ -174,6 +176,14 @@ describe('Executor', () => {
  inject: (state: ExpressionAstFunction['arguments']) => {
  return injectFn(state);
  },
+ migrations: {
+ '7.10.0': (((state: ExpressionAstFunction, version: string): ExpressionAstFunction => {
+ return migrateFn(state, version);
+ }) as any) as MigrateFunction,
+ '7.10.1': (((state: ExpressionAstFunction, version: string): ExpressionAstFunction => {
+ return migrateFn(state, version);
+ }) as any) as MigrateFunction,
+ },
  fn: jest.fn(),
  };
  executor.registerFunction(fooFn);
@@ -194,5 +204,26 @@ describe('Executor', () => {
  expect(extractFn).toBeCalledTimes(5);
  });
  });
+
+ describe('.migrate', () => {
+ test('calls migrate function for every expression function in expression', () => {
+ executor.migrate(
+ parseExpression('foo bar="baz" | foo bar={foo bar="baz" | foo bar={foo bar="baz"}}'),
+ '7.10.0'
+ );
+ expect(migrateFn).toBeCalledTimes(5);
+ });
+ });
+
+ describe('.migrateToLatest', () => {
+ test('calls extract function for every expression function in expression', () => {
+ migrateFn.mockClear();
+ executor.migrateToLatest(
+ parseExpression('foo bar="baz" | foo bar={foo bar="baz" | foo bar={foo bar="baz"}}'),
+ '7.10.0'
+ );
+ expect(migrateFn).toBeCalledTimes(10);
+ });
+ });
  });
 });

src/plugins/expressions/common/executor/executor.ts

@@ -32,7 +32,7 @@ import { typeSpecs } from '../expression_types/specs';
 import { functionSpecs } from '../expression_functions/specs';
 import { getByAlias } from '../util';
 import { SavedObjectReference } from '../../../../core/types';
-import { PersistableState } from '../../../kibana_utils/common';
+import { PersistableState, SerializableState } from '../../../kibana_utils/common';
 import { ExpressionExecutionParams } from '../service';
 
 export interface ExpressionExecOptions {
@@ -88,6 +88,20 @@ export class FunctionsRegistry implements IRegistry<ExpressionFunction> {
  }
 }
 
+const semverGte = (semver1: string, semver2: string) => {
+ const regex = /^([0-9]+)\.([0-9]+)\.([0-9]+)$/;
+ const matches1 = regex.exec(semver1) as RegExpMatchArray;
+ const matches2 = regex.exec(semver2) as RegExpMatchArray;
+
+ const [, major1, minor1, patch1] = matches1;
+ const [, major2, minor2, patch2] = matches2;
+
+ return (
+ major1 > major2 ||
+ (major1 === major2 && (minor1 > minor2 || (minor1 === minor2 && patch1 >= patch2)))
+ );
+};
+
 export class Executor<Context extends Record<string, unknown> = Record<string, unknown>>
  implements PersistableState<ExpressionAstExpression> {
  static createWithDefaults<Ctx extends Record<string, unknown> = Record<string, unknown>>(
@@ -249,6 +263,27 @@ export class Executor<Context extends Record<string, unknown> = Record<string, u
  return telemetryData;
  }
 
+ public migrate(ast: SerializableState, version: string) {
+ return this.walkAst(cloneDeep(ast) as ExpressionAstExpression, (fn, link) => {
+ if (!fn.migrations[version]) return link;
+ const updatedAst = fn.migrations[version](link) as ExpressionAstFunction;
+ link.arguments = updatedAst.arguments;
+ link.type = updatedAst.type;
+ });
+ }
+
+ public migrateToLatest(ast: unknown, version: string) {
+ return this.walkAst(cloneDeep(ast) as ExpressionAstExpression, (fn, link) => {
+ for (const key of Object.keys(fn.migrations)) {
+ if (semverGte(key, version)) {
+ const updatedAst = fn.migrations[key](link) as ExpressionAstFunction;
+ link.arguments = updatedAst.arguments;
+ link.type = updatedAst.type;
+ }
+ }
+ });
+ }
+
  public fork(): Executor<Context> {
  const initialState = this.state.get();
  const fork = new Executor<Context>(initialState);

src/plugins/expressions/common/expression_functions/expression_function.ts

@@ -24,7 +24,7 @@ import { ExpressionValue } from '../expression_types/types';
 import { ExecutionContext } from '../execution';
 import { ExpressionAstFunction } from '../ast';
 import { SavedObjectReference } from '../../../../core/types';
-import { PersistableState } from '../../../kibana_utils/common';
+import { PersistableState, SerializableState } from '../../../kibana_utils/common';
 
 export class ExpressionFunction implements PersistableState<ExpressionAstFunction['arguments']> {
  /**
@@ -76,6 +76,9 @@ export class ExpressionFunction implements PersistableState<ExpressionAstFunctio
  state: ExpressionAstFunction['arguments'],
  references: SavedObjectReference[]
  ) => ExpressionAstFunction['arguments'];
+ migrations: {
+ [key: string]: (state: SerializableState) => SerializableState;
+ };
 
  constructor(functionDefinition: AnyExpressionFunctionDefinition) {
  const {
@@ -91,6 +94,7 @@ export class ExpressionFunction implements PersistableState<ExpressionAstFunctio
  telemetry,
  inject,
  extract,
+ migrations,
  } = functionDefinition;
 
  this.name = name;
@@ -104,6 +108,7 @@ export class ExpressionFunction implements PersistableState<ExpressionAstFunctio
  this.telemetry = telemetry || ((s, c) => c);
  this.inject = inject || identity;
  this.extract = extract || ((s) => ({ state: s, references: [] }));
+ this.migrations = migrations || {};
 
  for (const [key, arg] of Object.entries(args || {})) {
  this.args[key] = new ExpressionFunctionParameter(key, arg);

src/plugins/expressions/common/service/expressions_services.ts

@@ -24,7 +24,7 @@ import { ExecutionContract } from '../execution/execution_contract';
 import { AnyExpressionTypeDefinition } from '../expression_types';
 import { AnyExpressionFunctionDefinition } from '../expression_functions';
 import { SavedObjectReference } from '../../../../core/types';
-import { PersistableState } from '../../../kibana_utils/common';
+import { PersistableState, SerializableState } from '../../../kibana_utils/common';
 import { Adapters } from '../../../inspector/common/adapters';
 import { ExecutionContextSearch } from '../execution';
 
@@ -303,6 +303,26 @@ export class ExpressionsService implements PersistableState<ExpressionAstExpress
  return this.executor.inject(state, references);
  };
 
+ /**
+ * Runs the migration (if it exists) for specified version. This will run a single migration step (ie from 7.10.0 to 7.10.1)
+ * @param state expression AST to update
+ * @param version defines which migration version to run
+ * @returns new migrated expression AST
+ */
+ public readonly migrate = (state: SerializableState, version: string) => {
+ return this.executor.migrate(state, version);
+ };
+
+ /**
+ * Migrates expression to the latest version
+ * @param state expression AST to update
+ * @param version the version of kibana in which expression was created
+ * @returns migrated expression AST
+ */
+ public readonly migrateToLatest = (state: unknown, version: string) => {
+ return this.executor.migrateToLatest(state, version);
+ };
+
  /**
  * Returns Kibana Platform *setup* life-cycle contract. Useful to return the
  * same contract on server-side and browser-side.